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

tweek/config/templates/env.template

@@ -0,0 +1,45 @@
+# ============================================================================
+# Tweek API Keys (~/.tweek/.env)
+# ============================================================================
+#
+# LLM provider keys for semantic security analysis (Layer 3).
+# Only ONE provider key is needed. Uncomment the one you want to use.
+#
+# This file has restricted permissions (chmod 600) and is protected by
+# Tweek's self-protection — only a human can edit it.
+#
+# Edit this file:  tweek config edit env
+# Test your key:   tweek config llm
+# ============================================================================
+
+
+# --- Google Gemini (RECOMMENDED — free tier available) ---
+# Get a free key: https://aistudio.google.com/apikey
+# Default model: gemini-2.0-flash
+#
+# GOOGLE_API_KEY=your-google-api-key-here
+
+
+# --- OpenAI ---
+# Get a key: https://platform.openai.com/api-keys
+# Default model: gpt-4o-mini
+#
+# OPENAI_API_KEY=your-openai-api-key-here
+
+
+# --- xAI (Grok) ---
+# Get a key: https://console.x.ai
+# Default model: grok-2
+#
+# XAI_API_KEY=your-xai-api-key-here
+
+
+# --- Anthropic ---
+# Get a key: https://console.anthropic.com/settings/keys
+# Default model: claude-3-5-haiku-latest
+#
+# IMPORTANT: Anthropic API keys are billed per-token, SEPARATELY from
+# Claude Pro/Max subscriptions. Using this WILL incur additional charges
+# on top of your plan. Google Gemini's free tier is recommended instead.
+#
+# ANTHROPIC_API_KEY=your-anthropic-api-key-here

tweek/config/templates/overrides.yaml.template

@@ -0,0 +1,121 @@
+# ============================================================================
+# Tweek Security Overrides (~/.tweek/overrides.yaml)
+# ============================================================================
+#
+# Human-only security configuration. This file is protected by Tweek's
+# self-protection — AI agents cannot modify it. Only a human editing
+# directly can change these settings.
+#
+# Features:
+#   - Whitelist: Exempt specific paths/tools/URLs from all screening
+#   - Pattern Toggles: Enable/disable individual detection patterns
+#   - Trust Levels: Control severity thresholds
+#   - Enforcement: Customize severity+confidence decision matrix
+#
+# Edit this file:  tweek config edit overrides
+# Full reference:  https://github.com/gettweek/tweek/blob/main/docs/CONFIGURATION.md
+# ============================================================================
+
+
+# ---------------------------------------------------------------------------
+# Whitelist Rules
+# ---------------------------------------------------------------------------
+# Skip ALL screening for matching targets. Use sparingly — whitelisted
+# content bypasses pattern matching, LLM review, and all other checks.
+#
+# whitelist:
+#   # Exempt a specific file for specific tools
+#   - path: ~/projects/my-app/templates.yaml
+#     tools: [Read]
+#     reason: "Known-safe templates file"
+#
+#   # Exempt an entire directory (prefix match)
+#   - path: ~/projects/trusted-project
+#     tools: [Read, Grep]
+#     reason: "Trusted project directory"
+#
+#   # Exempt a URL prefix
+#   - url_prefix: "https://api.example.com/"
+#     tools: [WebFetch]
+#     reason: "Internal API endpoint"
+#
+#   # Exempt a command prefix
+#   - tool: Bash
+#     command_prefix: "npm test"
+#     reason: "Running project tests"
+
+
+# ---------------------------------------------------------------------------
+# Pattern Toggles
+# ---------------------------------------------------------------------------
+# Control which of the 262 detection patterns are active.
+# Run 'tweek config list' to see all pattern names.
+#
+# patterns:
+#   # Globally disable specific patterns
+#   disabled:
+#     - name: env_command
+#       reason: "Used frequently in our workflow"
+#     - name: docker_mount_sensitive
+#       reason: "Our CI uses Docker volume mounts"
+#
+#   # Disable patterns only in specific directories
+#   scoped_disables:
+#     - name: hook_modification
+#       paths:
+#         - ~/projects/my-security-tool
+#       reason: "This repo contains hook management code"
+#
+#   # Force-enable patterns (overrides any disable rule)
+#   force_enabled:
+#     - credential_theft_critical
+#     - private_key_access
+
+
+# ---------------------------------------------------------------------------
+# Trust Level Configuration
+# ---------------------------------------------------------------------------
+# Controls how much screening is applied based on session type.
+#
+# Auto-detection: interactive sessions get full screening, automated
+# sessions (CI, cron, systemd) can have different thresholds.
+# Override with env var: TWEEK_TRUST_LEVEL=interactive|automated
+#
+# trust:
+#   default_mode: interactive       # Default when auto-detect is ambiguous
+#   interactive:
+#     min_severity: low             # Prompt on all severities
+#   automated:
+#     min_severity: high            # Only prompt on high and critical
+#     skip_llm_for_default_tier: true
+
+
+# ---------------------------------------------------------------------------
+# Enforcement Policy
+# ---------------------------------------------------------------------------
+# Customize the severity+confidence decision matrix.
+# Decisions: deny (hard block) | ask (prompt user) | log (silent allow)
+#
+# Default matrix:
+#   CRITICAL + deterministic → deny
+#   CRITICAL + heuristic/contextual → ask
+#   HIGH/MEDIUM → ask
+#   LOW → log
+#
+# enforcement:
+#   critical:
+#     deterministic: deny
+#     heuristic: ask
+#     contextual: ask
+#   high:
+#     deterministic: ask
+#     heuristic: ask
+#     contextual: ask
+#   medium:
+#     deterministic: ask
+#     heuristic: ask
+#     contextual: ask
+#   low:
+#     deterministic: log
+#     heuristic: log
+#     contextual: log

tweek/config/templates/tweek.yaml.template

@@ -0,0 +1,20 @@
+# ============================================================================
+# Tweek Hook Control (.tweek.yaml)
+# ============================================================================
+#
+# Per-directory control for Tweek security screening hooks.
+# Place this file in any directory to control whether hooks run there.
+#
+# This file is protected by Tweek's self-protection — only a human
+# editing directly can change these settings.
+#
+# Hooks:
+#   pre_tool_use   Screens tool calls BEFORE execution (can block)
+#   post_tool_use  Screens tool responses AFTER execution (advisory)
+#
+# Set to false to disable screening in this directory.
+# ============================================================================
+
+hooks:
+  pre_tool_use: true
+  post_tool_use: true

tweek/config/templates.py

@@ -0,0 +1,136 @@
+"""
+Tweek Configuration Templates
+
+Provides template loading and deployment for self-documenting config files.
+Templates are bundled with the package and deployed during installation.
+Users get well-commented files with all options visible and sensible defaults.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+TEMPLATES_DIR = Path(__file__).parent / "templates"
+
+# Registry of all user-facing configuration files.
+# Used by `tweek config edit` and the install flow.
+CONFIG_FILES = [
+    {
+        "id": "config",
+        "name": "Security Settings",
+        "template": "config.yaml.template",
+        "target_path": "~/.tweek/config.yaml",
+        "description": "LLM providers, tool tiers, rate limiting, session analysis",
+        "editable": True,
+    },
+    {
+        "id": "env",
+        "name": "API Keys",
+        "template": "env.template",
+        "target_path": "~/.tweek/.env",
+        "description": "LLM provider API keys (Google, OpenAI, xAI, Anthropic)",
+        "editable": True,
+    },
+    {
+        "id": "overrides",
+        "name": "Security Overrides",
+        "template": "overrides.yaml.template",
+        "target_path": "~/.tweek/overrides.yaml",
+        "description": "Whitelists, pattern toggles, trust levels (human-only)",
+        "editable": True,
+    },
+    {
+        "id": "hooks",
+        "name": "Hook Control",
+        "template": "tweek.yaml.template",
+        "target_path": ".tweek.yaml",
+        "description": "Per-directory enable/disable for pre and post screening",
+        "editable": True,
+    },
+    {
+        "id": "defaults",
+        "name": "Default Reference",
+        "template": None,
+        "target_path": str(Path(__file__).parent / "tiers.yaml"),
+        "description": "Bundled defaults — read-only reference for all options",
+        "editable": False,
+    },
+]
+
+
+def get_template_content(template_name: str) -> str:
+    """Read a template file and return its content."""
+    template_path = TEMPLATES_DIR / template_name
+    if not template_path.exists():
+        raise FileNotFoundError(f"Template not found: {template_path}")
+    return template_path.read_text()
+
+
+def deploy_template(
+    template_name: str,
+    target_path: Path,
+    overwrite: bool = False,
+) -> bool:
+    """Deploy a template to a target path.
+
+    Returns True if the file was created, False if skipped.
+    Does NOT overwrite existing files unless overwrite=True.
+    """
+    if target_path.exists() and not overwrite:
+        return False
+
+    content = get_template_content(template_name)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    target_path.write_text(content)
+
+    # Set restrictive permissions for sensitive files
+    if ".env" in target_path.name:
+        target_path.chmod(0o600)
+
+    return True
+
+
+def resolve_target_path(config_entry: dict, global_scope: bool = True) -> Path:
+    """Resolve the target path for a config file entry."""
+    path_str = config_entry["target_path"]
+    if path_str.startswith("~"):
+        return Path(path_str).expanduser()
+    if path_str.startswith("."):
+        if global_scope:
+            return Path.home() / path_str
+        return Path.cwd() / path_str
+    return Path(path_str)
+
+
+def deploy_all_templates(global_scope: bool = True) -> list[tuple[str, Path, bool]]:
+    """Deploy all templates that don't already exist.
+
+    Returns list of (name, path, created) tuples.
+    """
+    results = []
+    for entry in CONFIG_FILES:
+        if entry["template"] is None:
+            continue
+        target = resolve_target_path(entry, global_scope)
+        created = deploy_template(entry["template"], target)
+        results.append((entry["name"], target, created))
+    return results
+
+
+def append_active_section(target_path: Path, section_yaml: str) -> None:
+    """Append an active (uncommented) config section to a template-based file.
+
+    Used by the install flow to write user-selected LLM provider settings
+    below the template comments without destroying them (unlike yaml.dump).
+    """
+    existing = target_path.read_text() if target_path.exists() else ""
+    marker = "# --- Active Configuration (set during install) ---"
+
+    if marker in existing:
+        # Replace existing active section
+        parts = existing.split(marker)
+        existing = parts[0].rstrip()
+
+    target_path.write_text(
+        existing.rstrip() + "\n\n" + marker + "\n" + section_yaml + "\n"
+    )

tweek/config/tiers.yaml

@@ -9,7 +9,7 @@
 #
 # Security Layers:
 #   1. Rate Limiting    - Detect resource theft and burst attacks
-#   2. Pattern Match    - Regex patterns for known attack vectors (259 patterns)
+#   2. Pattern Match    - Regex patterns for known attack vectors (262 patterns)
 #   2.5 Heuristic Score - Signal-based scoring for confidence-gated LLM escalation
 #   3. LLM Review       - Semantic analysis using Claude Haiku or local LLM
 #   4. Session Scan     - Cross-turn anomaly detection
@@ -18,11 +18,11 @@
 version: 2
 
 # LLM Review Configuration
-# Supports: anthropic, openai, google, or any OpenAI-compatible endpoint
-# Provider "auto" checks: local (if enabled) → ANTHROPIC_API_KEY → OPENAI_API_KEY → GOOGLE_API_KEY
+# Supports: anthropic, openai, google, xai (Grok), or any OpenAI-compatible endpoint
+# Provider "auto" checks: local ONNX → GOOGLE_API_KEY → OPENAI_API_KEY → XAI_API_KEY → ANTHROPIC_API_KEY
 llm_review:
   enabled: true
-  provider: auto              # auto | local | anthropic | openai | google | fallback
+  provider: auto              # auto | local | anthropic | openai | google | xai | fallback
   model: auto                 # auto = provider default, or explicit model name
   base_url: null              # For OpenAI-compatible endpoints (Ollama, LM Studio, etc.)
   api_key_env: null           # Override env var name (default: provider-specific)
@@ -119,6 +119,7 @@ tools:
   # Dangerous - system commands, highest scrutiny
   Bash: dangerous
   Task: default  # Subagents inherit parent screening
+  Skill: safe    # Skill invocation — tracked for context, not screened itself
 
 # Skill classifications (user-defined skills)
 skills:

tweek/diagnostics.py

@@ -54,6 +54,7 @@ def run_health_checks(verbose: bool = False) -> List[HealthCheck]:
         _check_mcp_available,
         _check_proxy_config,
         _check_plugin_integrity,
+        _check_local_model,
         _check_llm_review,
     ]
 
@@ -590,6 +591,108 @@ def _check_plugin_integrity(verbose: bool = False) -> HealthCheck:
         )
 
 
+def _check_local_model(verbose: bool = False) -> HealthCheck:
+    """Check local classifier model status and verify inference works."""
+    try:
+        from tweek.security.local_model import LOCAL_MODEL_AVAILABLE, get_local_model
+        from tweek.security.model_registry import (
+            get_default_model_name,
+            get_model_size,
+            is_model_installed,
+            verify_model_hashes,
+        )
+    except ImportError:
+        return HealthCheck(
+            name="local_model",
+            label="Local Model",
+            status=CheckStatus.SKIPPED,
+            message="Local model module not available",
+            fix_hint="Install with: pip install tweek[local-models]",
+        )
+
+    if not LOCAL_MODEL_AVAILABLE:
+        return HealthCheck(
+            name="local_model",
+            label="Local Model",
+            status=CheckStatus.SKIPPED,
+            message="Dependencies not installed (optional)",
+            fix_hint="Install with: pip install tweek[local-models]",
+        )
+
+    default_name = get_default_model_name()
+
+    if not is_model_installed(default_name):
+        return HealthCheck(
+            name="local_model",
+            label="Local Model",
+            status=CheckStatus.WARNING,
+            message="Dependencies installed but model not downloaded",
+            fix_hint="Run: tweek model download",
+        )
+
+    # Model is installed — get size info
+    size = get_model_size(default_name)
+    size_str = f"{size / 1024 / 1024:.1f} MB" if size else "unknown size"
+
+    # Verify SHA-256 integrity before running inference
+    try:
+        hash_results = verify_model_hashes(default_name)
+        mismatched = [f for f, status in hash_results.items() if status == "mismatch"]
+        if mismatched:
+            files_str = ", ".join(mismatched)
+            return HealthCheck(
+                name="local_model",
+                label="Local Model",
+                status=CheckStatus.ERROR,
+                message=f"SHA-256 integrity check failed for: {files_str}",
+                fix_hint="Run: tweek model download --force  (to re-download)",
+            )
+    except Exception:
+        pass  # Hash verification is best-effort; don't block on it
+
+    # Run inference smoke test to verify the model actually works
+    try:
+        model = get_local_model(default_name)
+        if model is None:
+            return HealthCheck(
+                name="local_model",
+                label="Local Model",
+                status=CheckStatus.ERROR,
+                message=f"{default_name} installed ({size_str}) but failed to load",
+                fix_hint="Try: tweek model download --force",
+            )
+
+        result = model.predict("hello world")
+        if result is None or not hasattr(result, "risk_level"):
+            return HealthCheck(
+                name="local_model",
+                label="Local Model",
+                status=CheckStatus.ERROR,
+                message=f"{default_name} installed ({size_str}) but inference returned no result",
+                fix_hint="Try: tweek model download --force",
+            )
+
+        msg = f"{default_name} installed ({size_str}), inference OK"
+        if verbose:
+            msg += f" ({result.inference_time_ms:.0f}ms)"
+
+        return HealthCheck(
+            name="local_model",
+            label="Local Model",
+            status=CheckStatus.OK,
+            message=msg,
+        )
+
+    except Exception as e:
+        return HealthCheck(
+            name="local_model",
+            label="Local Model",
+            status=CheckStatus.ERROR,
+            message=f"{default_name} installed ({size_str}) but inference failed: {e}",
+            fix_hint="Try: tweek model download --force",
+        )
+
+
 def _check_llm_review(verbose: bool = False) -> HealthCheck:
     """Check LLM review provider availability and configuration."""
     try:
@@ -604,45 +707,22 @@ def _check_llm_review(verbose: bool = False) -> HealthCheck:
         reviewer = get_llm_reviewer()
 
         if not reviewer.enabled:
-            # Check which env vars are missing to give specific guidance
-            missing_keys = []
-            for provider, env_names in DEFAULT_API_KEY_ENVS.items():
-                if isinstance(env_names, list):
-                    if not any(os.environ.get(e) for e in env_names):
-                        missing_keys.append(f"{' or '.join(env_names)} ({provider})")
-                else:
-                    if not os.environ.get(env_names):
-                        missing_keys.append(f"{env_names} ({provider})")
-
             hint_parts = [
-                "To enable cloud LLM review for uncertain classifications:",
-                "  Set one of: " + ", ".join(
-                    k.split(" (")[0] for k in missing_keys
-                ),
+                "Set one of: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY,",
+                "  GEMINI_API_KEY, XAI_API_KEY, or other LLM provider API key",
+                "  as an environment variable, or configure a provider in",
+                "  ~/.tweek/config.yaml.",
+                "",
+                "  Alternatively, install a local model for offline review.",
+                "",
+                "  See: docs/CONFIGURATION.md (LLM Review Provider section)",
             ]
 
-            if not LOCAL_MODEL_AVAILABLE:
-                hint_parts.append(
-                    "  Or install the local model: pip install 'tweek[local]'"
-                )
-            else:
-                hint_parts.append(
-                    "  Local ONNX model is available but could not initialize"
-                )
-
-            hint_parts.append(
-                "  Or install Ollama (https://ollama.ai) for local LLM review"
-            )
-            hint_parts.append(
-                "  See: docs/CONFIGURATION.md or ~/.tweek/config.yaml"
-            )
-
             return HealthCheck(
                 name="llm_review",
                 label="LLM Review",
                 status=CheckStatus.WARNING,
-                message="No LLM provider available — review disabled, "
-                        "pattern matching and heuristic scoring still active",
+                message="No LLM provider configured — using pattern matching only",
                 fix_hint="\n".join(hint_parts),
             )
 

tweek/hooks/overrides.py

@@ -346,6 +346,10 @@ def is_protected_config_file(file_path: str) -> bool:
             if part == ".tweek":
                 return True
 
+        # Protect .tweek.yaml (per-directory hook control)
+        if resolved.name == ".tweek.yaml":
+            return True
+
     except (OSError, ValueError):
         pass
     return False

tweek/hooks/post_tool_use.py

@@ -11,7 +11,7 @@ web pages, documents, and other ingested content.
 
 Screening Pipeline:
 1. Language Detection — identify non-English content
-2. Pattern Matching — 259 regex patterns for known attack vectors
+2. Pattern Matching — 262 regex patterns for known attack vectors
 3. LLM Review — semantic analysis if non-English escalation triggers
 
 Claude Code PostToolUse Protocol:
@@ -284,6 +284,32 @@ def screen_content(
         except Exception:
             pass
 
+    # Provenance: escalate session taint based on findings
+    if (findings or llm_finding) and session_id:
+        try:
+            from tweek.memory.provenance import get_taint_store, severity_to_taint
+            _taint_store = get_taint_store()
+            if findings:
+                _highest_sev = max(
+                    findings,
+                    key=lambda f: {"critical": 4, "high": 3, "medium": 2, "low": 1}.get(f["severity"], 0)
+                )["severity"]
+            else:
+                _highest_sev = llm_finding.get("risk_level", "medium")
+            _taint_level = severity_to_taint(_highest_sev)
+            _taint_source = tool_input.get("file_path") or tool_input.get("url") or "unknown"
+            _taint_reason = f"{len(findings)} pattern(s) found"
+            if findings:
+                _taint_reason += f": {findings[0]['pattern_name']}"
+            _taint_store.record_taint(
+                session_id=session_id,
+                taint_level=_taint_level,
+                source=f"{tool_name}:{_taint_source}",
+                reason=_taint_reason,
+            )
+        except Exception:
+            pass  # Provenance is best-effort
+
     # Step 5: Content redaction for critical deterministic matches
     # Replace matched content with [REDACTED] to prevent AI from acting on it
     redacted_content = None
@@ -385,6 +411,16 @@ def process_hook(input_data: Dict[str, Any]) -> Dict[str, Any]:
         if whitelist_match:
             return {}
 
+    # Provenance: record external ingest for content-source tools
+    try:
+        from tweek.memory.provenance import get_taint_store, EXTERNAL_SOURCE_TOOLS
+        if session_id and tool_name in EXTERNAL_SOURCE_TOOLS:
+            _taint_store = get_taint_store()
+            _source = tool_input.get("file_path") or tool_input.get("url") or tool_name
+            _taint_store.record_external_ingest(session_id, f"{tool_name}:{_source}")
+    except Exception:
+        pass  # Provenance is best-effort
+
     # Extract text content from the response
     content = extract_response_content(tool_name, tool_response)
 
@@ -422,6 +458,15 @@ def process_hook(input_data: Dict[str, Any]) -> Dict[str, Any]:
 
 def main():
     """Read hook input from stdin, process, and output decision."""
+    # Check if post_tool_use hook is enabled for this directory
+    try:
+        from tweek.hooks.pre_tool_use import check_hook_enabled
+        if not check_hook_enabled("post_tool_use"):
+            print("{}")
+            return
+    except ImportError:
+        pass  # If import fails, default to enabled (fail safe)
+
     try:
         raw = sys.stdin.read()
         if not raw.strip():