@jaguilar87/gaia-ops 4.4.0 → 4.7.2

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

@@ -0,0 +1,181 @@
+"""
+Cloud pipe/redirect/chaining validator.
+
+Detects pipe, redirect, and command-chaining violations in cloud/infra commands.
+Cloud CLIs (gcloud, kubectl, aws, terraform, helm, flux) expose native flags
+for filtering and formatting — there is never a valid reason to pipe their output.
+
+This validator runs before tier classification so violations are caught early
+and the agent receives a corrective response rather than a blocked execution.
+"""
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from .hook_response import build_hook_permission_response
+
+logger = logging.getLogger(__name__)
+
+# Cloud/infra CLIs covered by this policy
+CLOUD_CLI_PATTERN = re.compile(
+    r'^\s*(gcloud|kubectl|aws|terraform|helm|flux)\b',
+    re.IGNORECASE
+)
+
+# Violation definitions: (name, regex, corrected_approach)
+VIOLATIONS = [
+    (
+        "pipe",
+        # Match a single pipe `|` but NOT logical OR `||`.
+        # Negative lookbehind (?<!\|) skips the second `|` of `||`.
+        # Negative lookahead (?!\|) skips the first `|` of `||`.
+        re.compile(r'(?<!\|)\|(?!\|)'),
+        (
+            "Use native output flags instead of piping to shell utilities.\n"
+            "  gcloud: --filter='...' --format='value(field)'\n"
+            "  kubectl: -o jsonpath='{...}' or -o go-template='{{...}}'\n"
+            "  aws: --query '...' --output text\n"
+            "  terraform: use terraform output or -json flag"
+        ),
+    ),
+    (
+        "redirect",
+        # Match `>` or `>>` for file redirection, but NOT:
+        # - `>&` (file descriptor duplication, e.g. `2>&1`)
+        # - `--` prefixed flags or other non-redirect uses
+        # Negative lookbehind (?<![>&]) avoids matching the `>` in `>&1`.
+        # Negative lookahead (?![>&]) avoids matching `>` when followed by `&`.
+        re.compile(r'(?<![>&])>{1,2}(?![>&])'),
+        (
+            "Use the Write tool to write output to a file instead of shell redirection.\n"
+            "  Write tool: creates or overwrites files cleanly without shell quoting issues.\n"
+            "  For append patterns, use the Edit tool or Read + Write."
+        ),
+    ),
+    (
+        "chaining",
+        # Match `;` or `&&` but NOT `||` (which is now correctly handled
+        # by the pipe regex above via negative lookahead).
+        re.compile(r';|&&'),
+        (
+            "Run each command as a separate, atomic Bash call instead of chaining.\n"
+            "  One command per step preserves exit-code isolation and avoids\n"
+            "  interactive prompts mid-chain that block Claude Code execution."
+        ),
+    ),
+]
+
+
+@dataclass
+class PipeViolation:
+    """A detected pipe/redirect/chaining violation."""
+    rule: str            # e.g. "pipe", "redirect", "chaining"
+    pattern: str         # the literal character(s) that triggered it
+    correction: str      # human-readable corrected approach
+
+
+def _find_violation(command: str) -> Optional[PipeViolation]:
+    """
+    Return the first pipe/redirect/chaining violation found in command,
+    or None if the command is clean.
+
+    Only checks commands that start with a cloud/infra CLI.
+    Skips characters inside single or double quoted strings to avoid
+    false positives (e.g. --filter='status:RUNNING' contains no violation).
+    """
+    if not CLOUD_CLI_PATTERN.match(command):
+        return None
+
+    # Strip quoted substrings before scanning for operators.
+    # This prevents false positives from flag values like --filter='a|b'.
+    unquoted = _strip_quoted_sections(command)
+
+    for rule_name, pattern, correction in VIOLATIONS:
+        match = pattern.search(unquoted)
+        if match:
+            return PipeViolation(
+                rule=rule_name,
+                pattern=match.group(0),
+                correction=correction,
+            )
+
+    return None
+
+
+def _strip_quoted_sections(text: str) -> str:
+    """
+    Replace content inside single and double quotes with spaces.
+    Handles simple quoting (no nested quotes, no escape sequences needed
+    for the operators we scan for).
+    """
+    result = []
+    in_single = False
+    in_double = False
+
+    for ch in text:
+        if ch == "'" and not in_double:
+            in_single = not in_single
+            result.append(ch)
+        elif ch == '"' and not in_single:
+            in_double = not in_double
+            result.append(ch)
+        elif in_single or in_double:
+            result.append(' ')  # mask the character
+        else:
+            result.append(ch)
+
+    return ''.join(result)
+
+
+def build_block_response(violation: PipeViolation, command: str) -> dict:
+    """
+    Build the structured JSON block that tells Claude Code to block the command
+    and return a corrective reason to the agent.
+
+    Uses permissionDecision: "deny" with exit 0 (NOT exit 2) so the agent
+    receives the correction message and adjusts rather than stopping entirely.
+
+    Args:
+        violation: The detected violation.
+        command:   The original command string (truncated in reason for readability).
+
+    Returns:
+        Dict suitable for json.dumps() and print() in the hook entry point.
+    """
+    truncated = command[:120] + ('...' if len(command) > 120 else '')
+
+    reason = (
+        f"Command-execution rule violated: no {violation.rule}s in cloud/infra commands.\n\n"
+        f"Violating pattern: '{violation.pattern}' detected in:\n"
+        f"  {truncated}\n\n"
+        f"Corrected approach:\n"
+        f"{violation.correction}"
+    )
+
+    return build_hook_permission_response("deny", reason)
+
+
+def validate_cloud_pipe(command: str) -> Optional[dict]:
+    """
+    Check a command for cloud pipe/redirect/chaining violations.
+
+    Returns a block-response dict if a violation is found, None otherwise.
+    The caller should json.dumps() the result and exit(0).
+
+    Args:
+        command: The raw bash command string.
+
+    Returns:
+        Block response dict, or None if command is clean.
+    """
+    violation = _find_violation(command)
+    if violation is None:
+        return None
+
+    logger.warning(
+        f"Cloud pipe violation [{violation.rule}] pattern='{violation.pattern}' "
+        f"in: {command[:80]}"
+    )
+    return build_block_response(violation, command)

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

@@ -0,0 +1,55 @@
+"""
+Shared builder for hookSpecificOutput responses.
+
+Claude Code hooks communicate permission decisions via a standard JSON
+structure.  This module provides a single builder so the three call sites
+(bash_validator allow, bash_validator deny, cloud_pipe_validator deny)
+share the same shape and field names.
+
+Internally delegates to the adapter layer's ``format_validation_response``
+for structural consistency, while preserving the original function signature
+so callers (bash_validator.py, cloud_pipe_validator) require zero changes.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Ensure the hooks directory is on sys.path so ``adapters`` resolves.
+_hooks_dir = str(Path(__file__).resolve().parent.parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from adapters.claude_code import ClaudeCodeAdapter
+from adapters.types import ValidationResult
+
+# Module-level singleton -- lightweight, no I/O in __init__.
+_adapter = ClaudeCodeAdapter()
+
+
+def build_hook_permission_response(
+    decision: str, reason: str, updated_input: dict | None = None
+) -> dict:
+    """Build a hookSpecificOutput dict for a PreToolUse permission decision.
+
+    Args:
+        decision: "allow", "deny", or "ask".
+        reason: Human-readable explanation forwarded to the agent.
+        updated_input: Optional modified tool input to pass through for
+            "ask" decisions (e.g. footer-stripped command).
+
+    Returns:
+        Dict suitable for ``json.dumps()`` and ``print()`` in the hook
+        entry point.
+    """
+    if decision == "ask":
+        response = _adapter.format_ask_response(reason, updated_input=updated_input)
+        return response.output
+
+    vr = ValidationResult(
+        allowed=(decision == "allow"),
+        reason=reason,
+    )
+    response = _adapter.format_validation_response(vr)
+    return response.output

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

@@ -0,0 +1,227 @@
+"""
+Shell Command Parser - Native Python Implementation
+
+Parses bash commands into individual components for permission validation.
+This is a workaround for Claude Code bug where settings.json permissions
+are not respected (GitHub Issue #13340).
+
+Features:
+- Parse piped commands: "cmd1 | cmd2" -> ["cmd1", "cmd2"]
+- Parse chained commands: "cmd1 && cmd2" -> ["cmd1", "cmd2"]
+- Parse semicolon-separated: "cmd1; cmd2" -> ["cmd1", "cmd2"]
+- Handle OR chains: "cmd1 || cmd2" -> ["cmd1", "cmd2"]
+- Preserve quoted strings: echo 'a|b' -> ["echo 'a|b'"]
+
+Dependencies: Python stdlib only (shlex, re)
+"""
+
+from typing import List, Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class ParsedCommand:
+    """Represents a parsed shell command component."""
+    command: str  # The actual command string
+    operator: Optional[str] = None  # The operator that follows (|, &&, ||, ;)
+
+    def __str__(self) -> str:
+        return self.command
+
+
+class ShellCommandParser:
+    """
+    Native Python shell command parser.
+
+    Parses bash commands into individual components while respecting:
+    - Single quotes (preserve everything inside)
+    - Double quotes (preserve with variable expansion awareness)
+    - Escape sequences
+    - Subshells
+    - Command substitution
+
+    Zero external dependencies - uses Python stdlib only.
+    """
+
+    # Shell operators that separate commands
+    OPERATORS = {
+        '|': 'pipe',
+        '&&': 'and',
+        '||': 'or',
+        ';': 'sequence',
+        '\n': 'newline'
+    }
+
+    def __init__(self):
+        """Initialize parser."""
+        pass
+
+    def parse(self, command: str) -> List[str]:
+        """
+        Parse shell command into individual components.
+
+        Args:
+            command: Full shell command string
+
+        Returns:
+            List of individual command strings
+
+        Example:
+            >>> parser = ShellCommandParser()
+            >>> parser.parse("ls | grep foo && wc -l")
+            ["ls", "grep foo", "wc -l"]
+
+            >>> parser.parse("echo 'test | grep' | cat")
+            ["echo 'test | grep'", "cat"]
+        """
+        if not command or not command.strip():
+            return []
+
+        # Normalize whitespace
+        command = command.strip()
+
+        # Split on operators while preserving quotes
+        components = self._split_on_operators(command)
+
+        # Clean and filter empty components
+        result = [comp.strip() for comp in components if comp.strip()]
+
+        return result
+
+    def _split_on_operators(self, command: str) -> List[str]:
+        """
+        Split command on operators (|, &&, ||, ;) while preserving quoted strings.
+
+        Uses state machine to track quote context.
+        """
+        components = []
+        current = []
+        i = 0
+
+        # Quote state
+        in_single_quote = False
+        in_double_quote = False
+
+        while i < len(command):
+            char = command[i]
+
+            # Handle escape sequences
+            if char == '\\' and i + 1 < len(command):
+                current.append(char)
+                current.append(command[i + 1])
+                i += 2
+                continue
+
+            # Handle single quotes
+            if char == "'" and not in_double_quote:
+                in_single_quote = not in_single_quote
+                current.append(char)
+                i += 1
+                continue
+
+            # Handle double quotes
+            if char == '"' and not in_single_quote:
+                in_double_quote = not in_double_quote
+                current.append(char)
+                i += 1
+                continue
+
+            # If inside quotes, add character and continue
+            if in_single_quote or in_double_quote:
+                current.append(char)
+                i += 1
+                continue
+
+            # Check for two-character operators (&&, ||)
+            if i + 1 < len(command):
+                two_char = command[i:i+2]
+                if two_char in ['&&', '||']:
+                    # Found operator - save current component
+                    if current:
+                        components.append(''.join(current))
+                        current = []
+                    i += 2
+                    continue
+
+            # Check for single-character operators (|, ;)
+            if char in ['|', ';', '\n']:
+                # Found operator - save current component
+                if current:
+                    components.append(''.join(current))
+                    current = []
+                i += 1
+                continue
+
+            # Regular character
+            current.append(char)
+            i += 1
+
+        # Add final component
+        if current:
+            components.append(''.join(current))
+
+        return components
+
+    def parse_with_operators(self, command: str) -> List[ParsedCommand]:
+        """
+        Parse command and preserve operator information.
+
+        Useful for understanding command flow (AND vs OR vs pipe).
+        """
+        if not command or not command.strip():
+            return []
+
+        commands = self.parse(command)
+        return [ParsedCommand(command=cmd) for cmd in commands]
+
+    def contains_operators(self, command: str) -> bool:
+        """Check if command contains shell operators (outside of quotes)."""
+        components = self.parse(command)
+        return len(components) > 1
+
+    def is_simple_command(self, command: str) -> bool:
+        """Check if command is a simple command (no operators)."""
+        return not self.contains_operators(command)
+
+
+# Singleton instance for reuse
+_shell_parser: Optional[ShellCommandParser] = None
+
+
+def get_shell_parser() -> ShellCommandParser:
+    """
+    Get singleton ShellCommandParser instance.
+
+    Returns:
+        ShellCommandParser instance
+    """
+    global _shell_parser
+    if _shell_parser is None:
+        _shell_parser = ShellCommandParser()
+    return _shell_parser
+
+
+def parse_command(command: str) -> List[str]:
+    """
+    Parse shell command into components (convenience function).
+
+    Args:
+        command: Shell command string
+
+    Returns:
+        List of command components
+    """
+    return get_shell_parser().parse(command)
+
+
+def is_compound_command(command: str) -> bool:
+    """
+    Check if command is compound (contains operators).
+
+    Args:
+        command: Shell command string
+
+    Returns:
+        True if compound, False if simple
+    """
+    return get_shell_parser().contains_operators(command)