@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-security/hooks/modules/security/prompt_validator.py

@@ -0,0 +1,40 @@
+"""Validate and classify resume prompts for security decision-making.
+
+Subsystem 1 of the pre_tool_use Task/Agent path.
+Runs FIRST -- if invalid, nothing else loads.
+
+Responsibilities:
+- Validates prompt is not empty, not malformed
+- Detects deprecated approval phrases
+- Detects nonce patterns
+- Returns: classification (nonce/malformed_nonce/deprecated/standard)
+"""
+
+from .approval_constants import (
+    NONCE_APPROVAL_PREFIX,
+    NONCE_APPROVAL_PATTERN,
+    DEPRECATED_APPROVAL_PHRASES,
+)
+
+
+def classify_resume_prompt(prompt: str) -> str:
+    """Classify a resume prompt into one of four categories.
+
+    Args:
+        prompt: The resume prompt string.
+
+    Returns:
+        'nonce' -- valid nonce approval token present
+        'malformed_nonce' -- APPROVE: prefix present but invalid nonce
+        'deprecated' -- deprecated approval phrase detected
+        'standard' -- normal resume prompt (no approval indicators)
+    """
+    stripped_prompt = prompt.strip()
+    if NONCE_APPROVAL_PATTERN.search(prompt):
+        return "nonce"
+    if stripped_prompt.startswith(NONCE_APPROVAL_PREFIX):
+        return "malformed_nonce"
+    prompt_lower = prompt.lower()
+    if any(phrase in prompt_lower for phrase in DEPRECATED_APPROVAL_PHRASES):
+        return "deprecated"
+    return "standard"

package/dist/gaia-security/hooks/modules/security/tiers.py

@@ -0,0 +1,196 @@
+"""
+Security tier definitions and classification.
+
+Provides tier metadata for commands after bash_validator has already
+enforced security decisions. The bash_validator is the primary gate;
+this module's classify_command_tier() is used for logging and state
+tracking.
+
+Tiers:
+- T0: Read-only operations (safe by elimination)
+- T1: Validation operations (validate, lint, fmt, check) -- local only
+- T2: Simulation operations (plan, diff, dry-run) -- may contact remote APIs
+- T3: State-modifying operations (mutative_verbs.py detection,
+  nonce-based approval via approval_grants.py)
+"""
+from __future__ import annotations
+
+import re
+import logging
+from enum import Enum
+from functools import lru_cache
+
+logger = logging.getLogger(__name__)
+
+
+class SecurityTier(str, Enum):
+    """Security tier classification for commands."""
+
+    T0_READ_ONLY = "T0"      # describe, get, show, list operations
+    T1_VALIDATION = "T1"     # validate, lint, fmt, check (local only)
+    T2_DRY_RUN = "T2"        # plan, diff, dry-run, template (simulation)
+    T3_BLOCKED = "T3"        # apply, reconcile, deploy operations (require approval)
+
+    def __str__(self) -> str:
+        return self.value
+
+    @property
+    def requires_approval(self) -> bool:
+        """Check if this tier requires user approval."""
+        return self == SecurityTier.T3_BLOCKED
+
+    @property
+    def description(self) -> str:
+        """Human-readable description of the tier."""
+        descriptions = {
+            SecurityTier.T0_READ_ONLY: "Read-only operation",
+            SecurityTier.T1_VALIDATION: "Validation operation",
+            SecurityTier.T2_DRY_RUN: "Dry-run operation",
+            SecurityTier.T3_BLOCKED: "State-modifying operation (requires approval)",
+        }
+        return descriptions.get(self, "Unknown tier")
+
+
+# T1: Local validation (no remote API calls)
+T1_PATTERNS = [
+    r"\bvalidate\b",
+    r"\blint\b",
+    r"\bcheck\b",
+    r"\bfmt\b",
+]
+
+# T2: Simulation (may contact remote APIs, but no state changes)
+T2_PATTERNS = [
+    r"\bplan\b",
+    r"\btemplate\b",
+    r"\bdiff\b",
+]
+
+# Ultra-common commands that should fast-path to T0
+# These are commands that appear in >80% of sessions
+# NOTE: Only include commands that are ALWAYS read-only regardless of flags.
+# "git branch" was removed because it has mutative variants (-D, -m, -M, etc.).
+ULTRA_COMMON_T0_COMMANDS = frozenset({
+    "ls", "pwd", "cat", "echo", "git status", "git diff",
+    "git log", "kubectl get",
+})
+
+
+@lru_cache(maxsize=512)
+def _classify_command_tier_cached(
+    command: str,
+    has_blocked_patterns: bool = False,
+) -> SecurityTier:
+    """
+    Classify command into security tier with LRU cache.
+
+    This is the internal cached implementation. Use classify_command_tier() instead.
+    """
+    if not command or not command.strip():
+        return SecurityTier.T3_BLOCKED
+
+    command = command.strip()
+
+    # Fast-path: Ultra-common T0 commands
+    words = command.split()
+    if len(words) >= 2:
+        prefix2 = f"{words[0]} {words[1]}"
+        if prefix2 in ULTRA_COMMON_T0_COMMANDS:
+            return SecurityTier.T0_READ_ONLY
+    if len(words) >= 1:
+        if words[0] in ULTRA_COMMON_T0_COMMANDS:
+            return SecurityTier.T0_READ_ONLY
+
+    # Blocked patterns already checked externally
+    if has_blocked_patterns:
+        return SecurityTier.T3_BLOCKED
+
+    # Check for dry-run operations (T2)
+    if "--dry-run" in command or "--plan-only" in command:
+        return SecurityTier.T2_DRY_RUN
+
+    # Check for simulation operations (T2: plan, diff, template)
+    for pattern in T2_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return SecurityTier.T2_DRY_RUN
+
+    # Check for local validation operations (T1: validate, lint, fmt, check)
+    for pattern in T1_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            return SecurityTier.T1_VALIDATION
+
+    # Use the mutative verb detector for T3 classification
+    from .mutative_verbs import (
+        detect_mutative_command,
+        CATEGORY_MUTATIVE,
+        CATEGORY_READ_ONLY,
+        CATEGORY_SIMULATION,
+    )
+    result = detect_mutative_command(command)
+    if result.is_mutative:
+        return SecurityTier.T3_BLOCKED
+    if result.category == CATEGORY_SIMULATION:
+        return SecurityTier.T2_DRY_RUN
+    if result.category == CATEGORY_READ_ONLY:
+        return SecurityTier.T0_READ_ONLY
+
+    # Not blocked, not mutative -> safe by elimination (T0)
+    return SecurityTier.T0_READ_ONLY
+
+
+def classify_command_tier(
+    command: str,
+    *,
+    pre_computed_tier: "SecurityTier | None" = None,
+) -> SecurityTier:
+    """
+    Classify command into security tier.
+
+    NOTE: This function is used for tier metadata AFTER the bash_validator has
+    already enforced security decisions. The bash_validator's own validation
+    order (blocked -> safe -> dangerous verbs -> GitOps -> tier) is the primary
+    security gate.
+
+    If *pre_computed_tier* is provided (e.g. from a ``BashValidationResult``
+    that already determined the tier during validation), it is returned
+    immediately without re-computing.
+
+    Classification order (when no pre-computed tier):
+    1. Ultra-common T0 fast-path (ls, git status, etc.)
+    2. Blocked patterns (T3) -- checked against pre-compiled patterns
+    3. Dry-run/simulation (T2) -- --dry-run, plan, diff, template
+    4. Local validation (T1) -- validate, lint, fmt, check
+    5. Mutative verb detector (T3) -- MUTATIVE verbs
+    6. Default T0 for everything else (safe by elimination)
+
+    Args:
+        command: Shell command to classify
+        pre_computed_tier: Optional tier already determined by an upstream
+            validator.  When provided the function returns it directly.
+
+    Returns:
+        SecurityTier classification
+    """
+    # Fast path: caller already knows the tier (e.g. BashValidationResult).
+    if pre_computed_tier is not None:
+        return pre_computed_tier
+
+    if not command or not command.strip():
+        return SecurityTier.T3_BLOCKED
+
+    command = command.strip()
+
+    # Import here to avoid circular imports
+    from .blocked_commands import get_blocked_patterns
+    blocked_patterns = get_blocked_patterns()
+
+    # Check for blocked operations first (T3)
+    # This must be done before caching since blocked_patterns come from module state
+    has_blocked = False
+    for pattern in blocked_patterns:
+        if pattern.search(command):
+            has_blocked = True
+            break
+
+    # Use cached classification
+    return _classify_command_tier_cached(command, has_blocked)

package/dist/gaia-security/hooks/modules/session/__init__.py

@@ -0,0 +1,10 @@
+"""Session management module.
+
+Provides:
+- session_manager: Session ID generation and management
+- session_event_injector: Filter and inject session events into agent prompts
+
+Note: session_state.py has been absorbed into modules.memory.episode_writer.
+"""
+
+__all__ = []

package/dist/gaia-security/hooks/modules/session/session_context_writer.py

@@ -0,0 +1,100 @@
+"""
+Session context writer for PostToolUse hook.
+
+Manages the active session context file, appending critical events
+(git commits, pushes, etc.) and applying a time-based retention policy.
+
+Public API:
+    - SessionContextWriter  (class with update_context method)
+"""
+
+import fcntl
+import json
+import logging
+import os
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Dict, Any
+
+from ..core.paths import get_session_dir
+
+logger = logging.getLogger(__name__)
+
+# Default retention period for session events
+DEFAULT_RETENTION_HOURS = 24
+
+
+class SessionContextWriter:
+    """Update active session context for critical events.
+
+    Thread-safe via file locking. Applies a configurable retention
+    policy (default 24h, override via SESSION_RETENTION_HOURS env var).
+    """
+
+    def __init__(self, context_path: Path = None):
+        """Initialize with optional custom context path.
+
+        Args:
+            context_path: Override path. Defaults to session_dir/context.json.
+        """
+        self.context_path = context_path or (get_session_dir() / "context.json")
+
+    def update_context(self, event_data: Dict[str, Any]) -> None:
+        """Update active context with event data.
+
+        Appends the event to the critical_events list, applies retention
+        policy, and writes back atomically with file locking.
+
+        Args:
+            event_data: Event dict (must include at least event_type).
+        """
+        try:
+            self.context_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # File lock to prevent race conditions from parallel tool calls
+            lock_path = self.context_path.with_suffix(".lock")
+            with open(lock_path, "w") as lock_file:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+                try:
+                    context: Dict[str, Any] = {}
+                    if self.context_path.exists():
+                        with open(self.context_path, "r") as f:
+                            context = json.load(f)
+
+                    if "critical_events" not in context:
+                        context["critical_events"] = []
+
+                    event_data["timestamp"] = datetime.now().isoformat()
+
+                    context["critical_events"].append(event_data)
+
+                    # Keep only events within retention window
+                    retention_hours = int(
+                        os.environ.get(
+                            "SESSION_RETENTION_HOURS",
+                            str(DEFAULT_RETENTION_HOURS),
+                        )
+                    )
+                    cutoff = datetime.now() - timedelta(hours=retention_hours)
+
+                    context["critical_events"] = [
+                        event
+                        for event in context["critical_events"]
+                        if event.get("timestamp")
+                        and datetime.fromisoformat(event["timestamp"]) > cutoff
+                    ]
+
+                    context["last_modified"] = datetime.now().isoformat()
+
+                    with open(self.context_path, "w") as f:
+                        json.dump(context, f, indent=2)
+                finally:
+                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+
+            logger.info(
+                "Updated context with event: %s",
+                event_data.get("event_type", "unknown"),
+            )
+
+        except Exception as e:
+            logger.error("Error updating active context: %s", e)

package/dist/gaia-security/hooks/modules/session/session_event_injector.py

@@ -0,0 +1,158 @@
+"""Session event injection for agent context.
+
+Subsystem 4 of the pre_tool_use Task/Agent path.
+
+Filters events by agent domain and injects them into agent prompts.
+Includes the hardcoded agent-to-event mapping.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Agent-to-event-type mapping: which events each agent should see
+AGENT_EVENT_FILTERS = {
+    "terraform-architect": ["git_commit", "infrastructure_change"],
+    "gitops-operator": ["git_commit", "git_push", "infrastructure_change"],
+    "devops-developer": ["git_commit", "file_modifications"],
+    "cloud-troubleshooter": "*",  # All events (needs full history for diagnosis)
+    "gaia-system": "*"  # All events (workflow analysis)
+}
+
+
+def filter_events_for_agent(events: list, agent: str) -> list:
+    """
+    Filter events relevant to agent domain.
+
+    Args:
+        events: List of critical events from session
+        agent: Agent type (e.g., "gitops-operator")
+
+    Returns:
+        Filtered list of events relevant to agent
+    """
+    agent_filter = AGENT_EVENT_FILTERS.get(agent, [])
+
+    # Return all events for wildcard agents
+    if agent_filter == "*":
+        return events[-10:]  # Last 10 events
+
+    # Filter by event type and return max 10
+    filtered = [
+        e for e in events[-20:]  # Search last 20
+        if e.get("event_type") in agent_filter
+    ]
+
+    return filtered[:10]  # Return max 10
+
+
+def format_events_summary(events: list) -> str:
+    """
+    Format events as readable summary for agent context.
+
+    Args:
+        events: List of filtered events
+
+    Returns:
+        Formatted markdown string
+    """
+    if not events:
+        return "No recent events"
+
+    lines = []
+
+    for event in events:
+        etype = event.get("event_type", "")
+        ts = event.get("timestamp", "")[:16]  # YYYY-MM-DDTHH:MM
+
+        if etype == "git_commit":
+            msg = event.get("commit_message", "")
+            hash_val = event.get("commit_hash", "")[:7]
+            if hash_val and msg:
+                lines.append(f"- [{ts}] Commit {hash_val}: {msg}")
+
+        elif etype == "git_push":
+            branch = event.get("branch", "")
+            if branch:
+                lines.append(f"- [{ts}] Pushed to {branch}")
+
+        elif etype == "file_modifications":
+            count = event.get("modification_count", 0)
+            if count:
+                lines.append(f"- [{ts}] Modified {count} files")
+
+        elif etype == "infrastructure_change":
+            cmd = event.get("command", "")
+            if cmd:
+                lines.append(f"- [{ts}] Infrastructure: {cmd}")
+
+    return "\n".join(lines) if lines else "No recent events"
+
+
+def build_session_events(
+    parameters: dict,
+    project_agents: list,
+) -> str | None:
+    """
+    Build session events string for agent context without mutating parameters.
+
+    Filters events by agent domain to avoid noise.
+    Returns the events string suitable for additionalContext injection,
+    or None if no events to inject.
+
+    Args:
+        parameters: Task tool parameters (read-only).
+        project_agents: List of valid project agent names.
+
+    Returns:
+        Session events string, or None if nothing to inject.
+    """
+    subagent_type = parameters.get("subagent_type", "")
+
+    # Only inject for project agents
+    if subagent_type not in project_agents:
+        logger.debug(f"Skipping session events for non-project agent: {subagent_type}")
+        return None
+
+    # Get session events
+    from ..core.paths import get_session_dir
+    context_path = get_session_dir() / "context.json"
+    if not context_path.exists():
+        logger.debug("No session context file found")
+        return None
+
+    try:
+        with open(context_path, 'r') as f:
+            context = json.load(f)
+
+        events = context.get("critical_events", [])
+        if not events:
+            logger.debug("No critical events in session")
+            return None
+
+        # Filter by agent domain
+        filtered = filter_events_for_agent(events, subagent_type)
+
+        if not filtered:
+            logger.debug(f"No relevant events for {subagent_type}")
+            return None
+
+        # Format events summary
+        events_summary = format_events_summary(filtered)
+
+        events_string = (
+            "# Recent Session Events (Auto-Injected, Last 24h)\n"
+            f"{events_summary}"
+        )
+        logger.info(f"Session events built for {subagent_type} ({len(filtered)} events)")
+
+        return events_string
+
+    except Exception as e:
+        logger.warning(f"Failed to build session events: {e}")
+        return None
+
+

package/dist/gaia-security/hooks/modules/session/session_manager.py

@@ -0,0 +1,31 @@
+"""
+Session ID generation and retrieval.
+
+Provides:
+    - get_or_create_session_id(): Get existing session ID or create new one
+"""
+
+import hashlib
+import logging
+import os
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+def get_or_create_session_id() -> str:
+    """Get existing session ID or create new one.
+
+    Checks the CLAUDE_SESSION_ID env var first.  If absent, generates a
+    new session ID from the current time and PID, stores it in the env var,
+    and returns it.
+    """
+    session_id = os.environ.get("CLAUDE_SESSION_ID")
+    if not session_id:
+        timestamp = datetime.now().strftime("%H%M%S")
+        hash_input = f"{timestamp}-{os.getpid()}"
+        session_hash = hashlib.sha256(hash_input.encode()).hexdigest()[:8]
+        session_id = f"session-{timestamp}-{session_hash}"
+        os.environ["CLAUDE_SESSION_ID"] = session_id
+        logger.debug(f"Generated new session_id: {session_id}")
+    return session_id

package/dist/gaia-security/hooks/modules/tools/__init__.py

@@ -0,0 +1,25 @@
+"""
+Tools module - Tool-specific validators.
+
+Provides:
+- bash_validator: Bash command validation
+- task_validator: Task tool validation with context enforcement
+- shell_parser: Shell command parsing (pipes, chains, etc.)
+"""
+
+from .shell_parser import ShellCommandParser, get_shell_parser, parse_command
+from .bash_validator import BashValidator, validate_bash_command
+from .task_validator import TaskValidator, validate_task_invocation
+
+__all__ = [
+    # Shell parser
+    "ShellCommandParser",
+    "get_shell_parser",
+    "parse_command",
+    # Bash validator
+    "BashValidator",
+    "validate_bash_command",
+    # Task validator
+    "TaskValidator",
+    "validate_task_invocation",
+]