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

tweek/config/models.py

@@ -0,0 +1,307 @@
+"""
+Pydantic models for Tweek configuration validation.
+
+These models define the schema for tiers.yaml (the main configuration file)
+and patterns.yaml (attack pattern definitions). They provide:
+- Type-safe configuration loading with automatic validation
+- Human-readable error messages for invalid configuration
+- JSON Schema export for documentation and IDE support
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+# ============================================================================
+# Enums
+# ============================================================================
+
+
+class SecurityTierValue(str, Enum):
+    """Valid security tier values."""
+    SAFE = "safe"
+    DEFAULT = "default"
+    RISKY = "risky"
+    DANGEROUS = "dangerous"
+
+
+class NonEnglishHandling(str, Enum):
+    """How non-English content is handled during screening."""
+    ESCALATE = "escalate"
+    TRANSLATE = "translate"
+    BOTH = "both"
+    NONE = "none"
+
+
+class PatternSeverity(str, Enum):
+    """Severity levels for attack patterns."""
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class PatternConfidence(str, Enum):
+    """Confidence levels for attack pattern matches."""
+    DETERMINISTIC = "deterministic"
+    HEURISTIC = "heuristic"
+    CONTEXTUAL = "contextual"
+
+
+# ============================================================================
+# Configuration Section Models
+# ============================================================================
+
+
+class LLMReviewLocalConfig(BaseModel):
+    """Configuration for local LLM server (Ollama, LM Studio)."""
+    enabled: bool = True
+    probe_timeout: float = Field(default=2.0, gt=0)
+    timeout_seconds: float = Field(default=30.0, gt=0)
+    ollama_host: Optional[str] = None
+    lm_studio_host: Optional[str] = None
+    preferred_models: List[str] = Field(default_factory=list)
+    validate_on_first_use: bool = True
+    min_validation_score: float = Field(default=0.6, ge=0.0, le=1.0)
+
+    model_config = {"extra": "allow"}
+
+
+class LLMReviewFallbackConfig(BaseModel):
+    """Configuration for LLM fallback chain."""
+    enabled: bool = True
+    order: List[str] = Field(default_factory=lambda: ["local", "anthropic", "openai"])
+
+    model_config = {"extra": "allow"}
+
+
+class LLMReviewConfig(BaseModel):
+    """Configuration for LLM-based semantic review."""
+    enabled: bool = True
+    provider: str = "auto"
+    model: str = "auto"
+    base_url: Optional[str] = None
+    api_key_env: Optional[str] = None
+    timeout_seconds: float = Field(default=15.0, gt=0)
+    local: LLMReviewLocalConfig = Field(default_factory=LLMReviewLocalConfig)
+    fallback: LLMReviewFallbackConfig = Field(default_factory=LLMReviewFallbackConfig)
+
+    model_config = {"extra": "allow"}
+
+
+class RateLimitingConfig(BaseModel):
+    """Configuration for request rate limiting."""
+    enabled: bool = True
+    burst_window_seconds: int = Field(default=10, gt=0)
+    burst_threshold: int = Field(default=5, gt=0)
+    max_per_minute: int = Field(default=60, gt=0)
+    max_dangerous_per_minute: int = Field(default=10, gt=0)
+    max_same_command_per_minute: int = Field(default=5, gt=0)
+
+    model_config = {"extra": "allow"}
+
+
+class SessionAnalysisConfig(BaseModel):
+    """Configuration for session-level analysis."""
+    enabled: bool = True
+    lookback_minutes: int = Field(default=30, gt=0)
+    alert_on_risk_score: float = Field(default=0.7, ge=0.0, le=1.0)
+
+    model_config = {"extra": "allow"}
+
+
+class HeuristicScorerConfig(BaseModel):
+    """Configuration for heuristic scoring bridge."""
+    enabled: bool = True
+    threshold: float = Field(default=0.4, ge=0.0, le=1.0)
+    log_all_scores: bool = False
+
+    model_config = {"extra": "allow"}
+
+
+class LocalModelConfig(BaseModel):
+    """Configuration for local ONNX model inference."""
+    enabled: bool = True
+    model: str = "auto"
+    escalate_to_llm: bool = True
+    escalate_min_confidence: float = Field(default=0.1, ge=0.0, le=1.0)
+    escalate_max_confidence: float = Field(default=0.9, ge=0.0, le=1.0)
+
+    @model_validator(mode="after")
+    def check_escalation_bounds(self) -> "LocalModelConfig":
+        if self.escalate_min_confidence >= self.escalate_max_confidence:
+            raise ValueError(
+                f"escalate_min_confidence ({self.escalate_min_confidence}) "
+                f"must be less than escalate_max_confidence ({self.escalate_max_confidence})"
+            )
+        return self
+
+    model_config = {"extra": "allow"}
+
+
+class TierDefinition(BaseModel):
+    """Definition of a security tier."""
+    description: str
+    screening: List[str] = Field(default_factory=list)
+
+
+class EscalationRule(BaseModel):
+    """A content-based escalation rule."""
+    pattern: str
+    description: str
+    escalate_to: SecurityTierValue
+
+    @field_validator("pattern")
+    @classmethod
+    def validate_regex(cls, v: str) -> str:
+        try:
+            re.compile(v)
+        except re.error as e:
+            raise ValueError(f"Invalid regex pattern: {e}") from e
+        return v
+
+
+class SensitiveDirectory(BaseModel):
+    """A sensitive directory that triggers path boundary escalation."""
+    pattern: str
+    escalate_to: SecurityTierValue
+    description: str = ""
+
+
+class PathBoundaryConfig(BaseModel):
+    """Configuration for path boundary escalation."""
+    enabled: bool = True
+    default_escalate_to: SecurityTierValue = SecurityTierValue.RISKY
+    sensitive_directories: List[SensitiveDirectory] = Field(default_factory=list)
+
+
+class OpenClawConfig(BaseModel):
+    """Configuration for OpenClaw integration."""
+    enabled: bool = False
+    gateway_port: int = Field(default=18789, gt=0, le=65535)
+    scanner_port: int = Field(default=9878, gt=0, le=65535)
+    plugin_installed: bool = False
+    preset: str = "cautious"
+
+    model_config = {"extra": "allow"}
+
+
+# ============================================================================
+# Root Configuration Model
+# ============================================================================
+
+
+class TweekConfig(BaseModel):
+    """
+    Root Pydantic model for Tweek configuration (tiers.yaml / config.yaml).
+
+    Validates the merged configuration from builtin, user, and project layers.
+    Uses extra="allow" at the root level to be forward-compatible with new
+    config keys added in future versions.
+    """
+    version: Optional[int] = None
+
+    # Core tool/skill classification
+    tools: Dict[str, SecurityTierValue] = Field(default_factory=dict)
+    skills: Dict[str, SecurityTierValue] = Field(default_factory=dict)
+    default_tier: SecurityTierValue = SecurityTierValue.DEFAULT
+
+    # Tier definitions
+    tiers: Dict[str, TierDefinition] = Field(default_factory=dict)
+
+    # Screening configuration
+    llm_review: Optional[LLMReviewConfig] = None
+    rate_limiting: Optional[RateLimitingConfig] = None
+    session_analysis: Optional[SessionAnalysisConfig] = None
+    heuristic_scorer: Optional[HeuristicScorerConfig] = None
+    local_model: Optional[LocalModelConfig] = None
+
+    # Escalation rules
+    escalations: List[EscalationRule] = Field(default_factory=list)
+
+    # Path boundary
+    path_boundary: Optional[PathBoundaryConfig] = None
+
+    # Non-English handling
+    non_english_handling: NonEnglishHandling = NonEnglishHandling.ESCALATE
+
+    # Integration configs
+    proxy: Optional[Dict[str, Any]] = None
+    mcp: Optional[Dict[str, Any]] = None
+    sandbox: Optional[Dict[str, Any]] = None
+    isolation_chamber: Optional[Dict[str, Any]] = None
+    plugins: Optional[Dict[str, Any]] = None
+    openclaw: Optional[OpenClawConfig] = None
+
+    model_config = {"extra": "allow"}
+
+    @field_validator("tools", mode="before")
+    @classmethod
+    def coerce_tool_tiers(cls, v: Any) -> Any:
+        """Accept string tier values and coerce to SecurityTierValue."""
+        if isinstance(v, dict):
+            return {k: SecurityTierValue(val) if isinstance(val, str) else val for k, val in v.items()}
+        return v
+
+    @field_validator("skills", mode="before")
+    @classmethod
+    def coerce_skill_tiers(cls, v: Any) -> Any:
+        """Accept string tier values and coerce to SecurityTierValue."""
+        if isinstance(v, dict):
+            return {k: SecurityTierValue(val) if isinstance(val, str) else val for k, val in v.items()}
+        return v
+
+
+# ============================================================================
+# Pattern Schema Model
+# ============================================================================
+
+
+class PatternDefinition(BaseModel):
+    """A single attack pattern definition from patterns.yaml."""
+    id: int
+    name: str
+    description: str
+    regex: str
+    severity: PatternSeverity
+    confidence: PatternConfidence
+    family: Optional[str] = None
+
+    @field_validator("regex")
+    @classmethod
+    def validate_regex(cls, v: str) -> str:
+        try:
+            re.compile(v)
+        except re.error as e:
+            raise ValueError(f"Invalid regex in pattern: {e}") from e
+        return v
+
+
+class PatternsConfig(BaseModel):
+    """Root model for patterns.yaml."""
+    version: int
+    pattern_count: int = 0
+    patterns: List[PatternDefinition] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def check_pattern_count(self) -> "PatternsConfig":
+        actual = len(self.patterns)
+        if self.pattern_count > 0 and actual != self.pattern_count:
+            raise ValueError(
+                f"pattern_count ({self.pattern_count}) does not match "
+                f"actual number of patterns ({actual})"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def check_unique_ids(self) -> "PatternsConfig":
+        ids = [p.id for p in self.patterns]
+        if len(ids) != len(set(ids)):
+            dupes = [i for i in ids if ids.count(i) > 1]
+            raise ValueError(f"Duplicate pattern IDs: {set(dupes)}")
+        return self

tweek/config/patterns.yaml

@@ -1,5 +1,5 @@
 # Tweek Attack Pattern Definitions v3
-# All 215 patterns included FREE
+# All 262 patterns included FREE
 #
 # Update via: tweek update (pulls from github.com/gettweek/tweek)
 #
@@ -25,7 +25,7 @@
 # PRO tier adds: LLM review, session analysis, rate limiting
 
 version: 5
-pattern_count: 259
+pattern_count: 262
 
 patterns:
   # ============================================================================
@@ -711,7 +711,7 @@ patterns:
   - id: 83
     name: document_metadata_injection
     description: "Hidden instructions in document metadata"
-    regex: '(author|title|subject|keywords|description)\s*[=:]\s*.*?(execute|run|ignore|override|bypass)'
+    regex: '(author|title|subject|keywords|description)\s*[=:]\s*[^\n]{0,80}(execute|run|ignore|override|bypass)'
     severity: high
     confidence: heuristic
     family: prompt_injection
@@ -736,7 +736,7 @@ patterns:
   - id: 86
     name: log_to_leak
     description: "Log-To-Leak covert channel attack"
-    regex: '(log|write|append|print).*?(secret|credential|token|key|password).*?(file|output|stream)'
+    regex: '(log|write|append|print)[^\n]{0,60}(secret|credential|token|key|password)[^\n]{0,60}(file|output|stream)'
     severity: high
     confidence: heuristic
     family: covert_channels
@@ -1514,7 +1514,7 @@ patterns:
   - id: 174
     name: leetspeak_instruction_bypass
     description: "Heavy character substitution of security-critical words"
-    regex: '([sS5$][yY][sS5$][tT7][eE3][mM]\s*[pP][rR][0oO][mM][pP][tT7]|[1iI][nN][sS5$][tT7][rR][uU][cC][tT7]|[cC][0oO][nN][fF][1iI][gG]|[eE3][xX][eE3][cC][uU][tT7][eE3])'
+    regex: '((?=[a-zA-Z01357$]*[01357$])[sS5$][yY][sS5$][tT7][eE3][mM]\s*[pP][rR][0oO][mM][pP][tT7]|(?=[a-zA-Z01357$]*[01357$])[1iI][nN][sS5$][tT7][rR][uU][cC][tT7]|(?=[a-zA-Z01357$]*[01357$])[cC][0oO][nN][fF][1iI][gG]|(?=[a-zA-Z01357$]*[01357$])[eE3][xX][eE3][cC][uU][tT7][eE3])'
     severity: medium
     confidence: contextual
     family: prompt_injection
@@ -2251,3 +2251,27 @@ patterns:
     severity: low
     confidence: contextual
     family: prompt_injection
+
+  - id: 260
+    name: summarize_instructions_extraction
+    description: "Summarization-based system prompt extraction"
+    regex: '(summarize|recap|outline|condense|describe|paraphrase)\s+.{0,30}(instructions|prompt|rules|guidelines|directives|configuration)\s+.{0,20}(given|told|provided|have|follow|received|programmed)'
+    severity: medium
+    confidence: contextual
+    family: prompt_injection
+
+  - id: 261
+    name: special_instructions_probe
+    description: "Probing for special instructions or unique capabilities"
+    regex: 'what\s+.{0,20}(instructions|capabilities|directives|rules)\s+.{0,30}(do\s+you\s+have|make\s+you|were\s+you|that\s+you)'
+    severity: medium
+    confidence: contextual
+    family: prompt_injection
+
+  - id: 262
+    name: system_prompt_reference_broad
+    description: "Broad references to system prompt in extraction context"
+    regex: '((your|my|the|its)\s+.{0,20}system[\s_]+prompt|system[\s_]+prompt\s*(say|would\s+say|output|reveal|share|display)|output\s+(system[\s_]+)?(prompt|configuration)\b|(instructions|directives)\s+(you|I|they|it)\s+(received|were\s+given|have\b|follow|got)|what.s\s+your\s+system[\s_]+prompt)'
+    severity: medium
+    confidence: contextual
+    family: prompt_injection

tweek/config/templates/config.yaml.template

@@ -0,0 +1,212 @@
+# ============================================================================
+# Tweek User Configuration (~/.tweek/config.yaml)
+# ============================================================================
+#
+# This file overrides Tweek's bundled defaults. Only uncomment what you
+# want to change -- everything else uses safe production defaults.
+#
+# Config hierarchy (highest priority wins):
+#   1. Project:  .tweek/config.yaml      (per-project overrides)
+#   2. User:     ~/.tweek/config.yaml     (this file)
+#   3. Bundled:  tweek/config/tiers.yaml  (production defaults)
+#
+# Commands:
+#   tweek config edit           Open this file in your editor
+#   tweek config show-defaults  View all bundled defaults
+#   tweek config validate       Check for errors
+#   tweek config list           Show current tool/skill tiers
+#   tweek config preset <name>  Apply a preset (paranoid|cautious|trusted)
+#
+# Full docs: https://github.com/gettweek/tweek/blob/main/docs/CONFIGURATION.md
+# ============================================================================
+
+
+# ---------------------------------------------------------------------------
+# LLM Review Provider (Layer 3 — semantic analysis)
+# ---------------------------------------------------------------------------
+# Analyzes suspicious commands/content using an LLM for deeper screening.
+# Works alongside pattern matching (Layer 2) — not a replacement.
+#
+# Auto-detect order: Local ONNX model > Google > OpenAI > xAI > Anthropic
+#
+# IMPORTANT: API keys go in ~/.tweek/.env (not here). Run:
+#   tweek config edit env
+#
+# BILLING NOTE: Anthropic API keys are billed per-token, SEPARATELY from
+# Claude Pro/Max subscriptions. Google Gemini has a free tier — recommended.
+#
+# llm_review:
+#   enabled: true
+#   provider: auto              # auto | google | openai | xai | anthropic | local
+#   model: auto                 # auto = provider default. Defaults per provider:
+#                               #   google:    gemini-2.0-flash
+#                               #   openai:    gpt-4o-mini
+#                               #   xai:       grok-2
+#                               #   anthropic: claude-3-5-haiku-latest
+#                               #   local:     deberta-v3-injection
+#   timeout_seconds: 5.0        # Max wait for LLM response
+#   base_url: null              # For OpenAI-compatible endpoints (Ollama, LM Studio, etc.)
+#   api_key_env: null           # Override env var name (default: provider-specific)
+#
+#   # Local LLM server settings (Ollama, LM Studio)
+#   local:
+#     enabled: true
+#     probe_timeout: 0.5        # Max probe time per server (seconds)
+#     timeout_seconds: 3.0      # Per-request timeout (local should be fast)
+#     ollama_host: null          # Override (default: OLLAMA_HOST env or localhost:11434)
+#     lm_studio_host: null       # Override (default: localhost:1234)
+#     preferred_models: []       # User override for model ranking
+#     validate_on_first_use: true
+#     min_validation_score: 0.6  # Must pass 3/5 validation commands
+#
+#   # Fallback chain (try local first, then cloud)
+#   fallback:
+#     enabled: true
+#     order: [local, cloud]
+
+
+# ---------------------------------------------------------------------------
+# Local ONNX Model (Layer 3 — on-device classifier)
+# ---------------------------------------------------------------------------
+# On-device prompt injection classifier. No API key needed.
+# Install: pip install tweek[local-models] && tweek model download
+# When installed, runs before cloud LLM and escalates uncertain results.
+#
+# local_model:
+#   enabled: true
+#   model: auto                     # auto = default model, or explicit name
+#   escalate_to_llm: true           # Escalate uncertain results to cloud LLM
+#   escalate_min_confidence: 0.1    # Below this = safe, skip escalation
+#   escalate_max_confidence: 0.9    # Above this = use local result, skip escalation
+
+
+# ---------------------------------------------------------------------------
+# Rate Limiting (Layer 1 — burst detection)
+# ---------------------------------------------------------------------------
+# Detects rapid-fire tool calls that may indicate automated attacks.
+#
+# rate_limiting:
+#   enabled: true
+#   burst_window_seconds: 5         # Time window for burst detection
+#   burst_threshold: 15             # Max calls in burst window
+#   max_per_minute: 60              # Overall rate limit
+#   max_dangerous_per_minute: 10    # Limit for dangerous-tier tools
+#   max_same_command_per_minute: 5  # Repeated identical commands
+
+
+# ---------------------------------------------------------------------------
+# Session Analysis (Layer 4 — cross-turn anomaly detection)
+# ---------------------------------------------------------------------------
+# Tracks patterns across multiple tool calls to detect multi-step attacks.
+#
+# session_analysis:
+#   enabled: true
+#   lookback_minutes: 30            # How far back to analyze
+#   alert_on_risk_score: 0.5        # Threshold for session risk alerts
+
+
+# ---------------------------------------------------------------------------
+# Heuristic Scorer (Layer 2.5 — signal-based escalation)
+# ---------------------------------------------------------------------------
+# Bridges pattern matching and LLM review. When no regex matches but
+# content looks suspicious, scores it and may escalate to LLM.
+#
+# heuristic_scorer:
+#   enabled: true
+#   threshold: 0.4                  # Score [0.0-1.0] to trigger LLM escalation
+#   log_all_scores: false           # Log below-threshold scores (for tuning)
+
+
+# ---------------------------------------------------------------------------
+# Tool Tier Overrides
+# ---------------------------------------------------------------------------
+# Override the default security tier for specific tools.
+# Tiers: safe | default | risky | dangerous
+#
+# Bundled defaults:
+#   Read:         default    (read-only but needs path screening)
+#   Glob:         safe       (file pattern matching)
+#   Grep:         safe       (search file contents)
+#   Edit:         default    (modify existing files)
+#   Write:        risky      (create/overwrite files)
+#   NotebookEdit: default    (edit Jupyter notebooks)
+#   WebFetch:     risky      (fetch content from URLs)
+#   WebSearch:    risky      (search the web)
+#   Bash:         dangerous  (execute shell commands)
+#   Task:         default    (spawn subagent tasks)
+#
+# tools:
+#   Read: default
+#   Bash: dangerous
+
+
+# ---------------------------------------------------------------------------
+# Skill Tier Overrides
+# ---------------------------------------------------------------------------
+# Override the default tier for Claude Code skills.
+#
+# Bundled defaults:
+#   review-pr:        safe       (read-only PR review)
+#   explore:          safe       (read-only codebase exploration)
+#   commit:           default    (git commit operations)
+#   frontend-design:  risky      (generate frontend code)
+#   dev-browser:      risky      (browser automation)
+#   deploy:           dangerous  (deployment operations)
+#
+# skills:
+#   commit: default
+#   deploy: dangerous
+
+
+# ---------------------------------------------------------------------------
+# Non-English Language Handling
+# ---------------------------------------------------------------------------
+# English-only regex patterns can miss injection in other languages.
+# Options:
+#   escalate  - Auto-escalate to LLM review tier (default, recommended)
+#   translate - Translate to English before pattern matching (requires API key)
+#   both      - Escalate AND translate (maximum coverage)
+#   none      - No special handling (English-only patterns may miss attacks)
+#
+# non_english_handling: escalate
+
+
+# ---------------------------------------------------------------------------
+# Content-Based Escalations
+# ---------------------------------------------------------------------------
+# Regex patterns that bump a tool's tier based on content.
+# These ADD to the bundled escalations (they don't replace them).
+#
+# escalations:
+#   - pattern: '\b(prod|production)\b'
+#     description: "Production environment reference"
+#     escalate_to: risky
+#
+#   - pattern: 'rm\s+(-rf|-fr|--recursive)'
+#     description: "Recursive deletion"
+#     escalate_to: dangerous
+
+
+# ---------------------------------------------------------------------------
+# Path Boundary Escalation
+# ---------------------------------------------------------------------------
+# Escalates tier when tools access files outside the project directory.
+#
+# path_boundary:
+#   enabled: true
+#   default_escalate_to: risky     # Generic out-of-project access
+#   sensitive_directories:
+#     - pattern: ".ssh"
+#       escalate_to: dangerous
+#       description: "SSH directory access"
+#     - pattern: ".aws"
+#       escalate_to: dangerous
+#       description: "AWS credentials directory"
+
+
+# ---------------------------------------------------------------------------
+# Default Tier
+# ---------------------------------------------------------------------------
+# Fallback tier for tools/skills not explicitly classified.
+#
+# default_tier: default

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