@jaguilar87/gaia-ops 4.4.0 → 4.7.2

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

@@ -0,0 +1,86 @@
+"""
+Actionable BLOCKED message formatter for permanently blocked commands.
+
+When the hook blocks a T3 command (exit 2), this module produces messages that:
+- Line 1: What domain was blocked and why (irreversible)
+- Line 2: The specific suggestion (from BLOCKED_COMMAND_SUGGESTIONS if available)
+- Line 3: Which agent to dispatch to (mapped from command category)
+
+This replaces the generic "[BLOCKED] Command blocked by security policy" message
+with actionable guidance for the orchestrator.
+"""
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Category-to-agent mapping: which specialist handles remediation
+CATEGORY_AGENT_MAP = {
+    "aws_critical": "terraform-architect",
+    "gcp_critical": "terraform-architect",
+    "terraform_destroy": "terraform-architect",
+    "kubernetes_critical": "gitops-operator",
+    "flux_critical": "gitops-operator",
+    "git_destructive": "devops-developer",
+    "docker_critical": "devops-developer",
+    "npm_critical": "devops-developer",
+    "sql_critical": "devops-developer",
+    "disk_operations": "devops-developer",
+    "rm_critical": "devops-developer",
+    "repo_delete": "devops-developer",
+}
+
+
+def format_blocked_message(result) -> str:
+    """Format a blocked command result into an actionable message.
+
+    Args:
+        result: A BashValidationResult with tier, reason, and suggestions fields.
+
+    Returns:
+        A multi-line message with domain, suggestion, and agent routing.
+    """
+    # Extract category from reason (format: "Command blocked by security policy: <category>")
+    category = _extract_category(result.reason)
+
+    # Line 1: What was blocked and why
+    msg = f"[BLOCKED] {result.reason} (irreversible operation)\n"
+
+    # Line 2: Specific suggestion
+    suggestion = _get_suggestion(result, category)
+    if suggestion:
+        msg += f"Suggestion: {suggestion}\n"
+
+    # Line 3: Agent to dispatch to
+    agent = CATEGORY_AGENT_MAP.get(category)
+    if agent:
+        msg += f"Dispatch to: {agent}\n"
+
+    return msg
+
+
+def _extract_category(reason: str) -> Optional[str]:
+    """Extract category name from the reason string.
+
+    The reason format from bash_validator is:
+        "Command blocked by security policy: <category>"
+    """
+    prefix = "Command blocked by security policy: "
+    if prefix in reason:
+        return reason.split(prefix, 1)[1].strip()
+    return None
+
+
+def _get_suggestion(result, category: Optional[str]) -> Optional[str]:
+    """Get the best suggestion for the blocked command.
+
+    Prefers the suggestion from the result (sourced from BLOCKED_COMMAND_SUGGESTIONS),
+    falls back to the reason text.
+    """
+    if result.suggestions:
+        return result.suggestions[0]
+    if category:
+        return f"Category '{category}' commands are permanently blocked"
+    return result.reason

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

@@ -0,0 +1,130 @@
+"""
+Semantic command analysis helpers for security decisions.
+
+This module builds an analysis-friendly representation of a shell command
+without mutating the original command string that will be executed.
+
+Key properties:
+- Idempotent: analyzing a normalized command produces the same semantic view.
+- CLI-agnostic: relies on token structure, not a large per-CLI global-flag table.
+- Non-destructive: the real command is never rewritten for execution.
+"""
+
+import functools
+import shlex
+from dataclasses import dataclass
+from typing import Iterable, Tuple
+
+# Scan enough semantic tokens to cover CLIs with multiple resource segments and
+# several global flag/value pairs before the real verb.
+SEMANTIC_SCAN_LIMIT = 12
+
+
+@dataclass(frozen=True)
+class CommandSemantics:
+    """Semantic view of a shell command for policy analysis."""
+
+    raw_command: str = ""
+    tokens: Tuple[str, ...] = ()
+    base_cmd: str = ""
+    args: Tuple[str, ...] = ()
+    flag_tokens: Tuple[str, ...] = ()
+    non_flag_tokens: Tuple[str, ...] = ()
+    semantic_tokens: Tuple[str, ...] = ()
+    semantic_head_tokens: Tuple[str, ...] = ()
+
+    @property
+    def normalized_command(self) -> str:
+        """Return the canonical analysis form of the command."""
+        return " ".join(self.semantic_tokens)
+
+
+def tokenize_command(command: str) -> Tuple[str, ...]:
+    """Tokenize a shell command safely, preserving quoted substrings."""
+    if not command or not command.strip():
+        return ()
+    try:
+        return tuple(shlex.split(command.strip()))
+    except ValueError:
+        # Fall back to a simple split for malformed quoting. This keeps the
+        # security layer best-effort instead of crashing on parse errors.
+        return tuple(command.strip().split())
+
+
+@functools.lru_cache(maxsize=128)
+def analyze_command(command: str, semantic_scan_limit: int = SEMANTIC_SCAN_LIMIT) -> CommandSemantics:
+    """Build an idempotent semantic representation for security analysis."""
+    raw_command = command.strip() if command else ""
+    tokens = tokenize_command(raw_command)
+    if not tokens:
+        return CommandSemantics(raw_command=raw_command)
+
+    base_cmd = _pathless(tokens[0]).lower()
+    args = tuple(tokens[1:])
+
+    flag_tokens = []
+    non_flag_tokens = []
+    for token in args:
+        if _is_flag(token):
+            flag_tokens.extend(_normalize_flag_token(token))
+            continue
+        non_flag_tokens.append(token.lower())
+
+    semantic_tokens = (base_cmd, *non_flag_tokens)
+    head_size = max(1, semantic_scan_limit + 1)
+
+    return CommandSemantics(
+        raw_command=raw_command,
+        tokens=tokens,
+        base_cmd=base_cmd,
+        args=args,
+        flag_tokens=tuple(flag_tokens),
+        non_flag_tokens=tuple(non_flag_tokens),
+        semantic_tokens=tuple(semantic_tokens),
+        semantic_head_tokens=tuple(semantic_tokens[:head_size]),
+    )
+
+
+def _contains_ordered_sequence(tokens: Iterable[str], sequence: Iterable[str]) -> bool:
+    """Return True when all sequence tokens appear in order, allowing gaps.
+
+    Internal helper -- callers must supply pre-lowercased inputs.
+    Both ``tokens`` (semantic_head_tokens) and ``sequence``
+    (SemanticBlockedRule.sequence) are already lowercase when produced by
+    :func:`analyze_command` and :class:`SemanticBlockedRule`.
+    """
+    needles = tuple(sequence)
+    if not needles:
+        return False
+
+    index = 0
+    for token in tokens:
+        if token == needles[index]:
+            index += 1
+            if index == len(needles):
+                return True
+    return False
+
+
+def _pathless(token: str) -> str:
+    """Strip a leading path prefix from an executable token."""
+    return token.rsplit("/", 1)[-1] if "/" in token else token
+
+
+def _is_flag(token: str) -> bool:
+    """Check whether a token is flag-shaped."""
+    return token.startswith("-") and token != "-"
+
+
+def _normalize_flag_token(token: str) -> Tuple[str, ...]:
+    """Normalize flag tokens for matching while preserving exact variants."""
+    token_lower = token.lower()
+
+    if token_lower.startswith("--"):
+        return (token_lower.split("=", 1)[0],)
+
+    normalized = [token_lower]
+    short_body = token_lower[1:]
+    if len(short_body) > 1 and short_body.isalpha():
+        normalized.extend(f"-{char}" for char in short_body)
+    return tuple(normalized)

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

@@ -0,0 +1,179 @@
+"""
+GitOps workflow validation for kubectl, helm, and flux commands.
+
+Ensures commands follow GitOps principles:
+- No direct cluster modifications
+- Use --dry-run for apply operations
+- Prefer read-only commands
+"""
+
+import re
+import logging
+from typing import List, Optional
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class GitOpsValidationResult:
+    """Result of GitOps validation."""
+    allowed: bool
+    reason: str
+    severity: str = "info"  # info, warning, high, critical
+    suggestions: List[str] = field(default_factory=list)
+
+
+# Safe read-only commands (always allowed)
+SAFE_KUBECTL_COMMANDS = [
+    r'kubectl\s+get',
+    r'kubectl\s+describe',
+    r'kubectl\s+logs',
+    r'kubectl\s+top',
+    r'kubectl\s+explain',
+    r'kubectl\s+version',
+    r'kubectl\s+cluster-info',
+    r'kubectl\s+config\s+view',
+    r'kubectl\s+api-resources',
+    r'kubectl\s+api-versions',
+]
+
+SAFE_FLUX_COMMANDS = [
+    r'flux\s+get',
+    r'flux\s+check',
+    r'flux\s+version',
+    r'flux\s+logs',
+    r'flux\s+stats',
+    r'flux\s+tree',
+]
+
+SAFE_HELM_COMMANDS = [
+    r'helm\s+list',
+    r'helm\s+status',
+    r'helm\s+history',
+    r'helm\s+template',
+    r'helm\s+lint',
+    r'helm\s+version',
+    r'helm\s+show',
+    r'helm\s+search',
+]
+
+# Forbidden commands (modify cluster state)
+FORBIDDEN_KUBECTL_COMMANDS = [
+    r'kubectl\s+apply(?!\s+.*--dry-run)',
+    r'kubectl\s+create(?!\s+.*--dry-run)',
+    r'kubectl\s+patch',
+    r'kubectl\s+replace',
+    r'kubectl\s+delete',
+    r'kubectl\s+scale',
+    r'kubectl\s+rollout\s+restart',
+    r'kubectl\s+annotate(?!\s+.*--dry-run)',
+    r'kubectl\s+label(?!\s+.*--dry-run)',
+]
+
+FORBIDDEN_FLUX_COMMANDS = [
+    r'flux\s+create',
+    r'flux\s+delete',
+    r'flux\s+suspend',
+    r'flux\s+resume',
+]
+
+FORBIDDEN_HELM_COMMANDS = [
+    r'helm\s+install(?!\s+.*--dry-run)',
+    r'helm\s+upgrade(?!\s+.*--dry-run)',
+    r'helm\s+uninstall',
+    r'helm\s+rollback',
+]
+
+
+def is_safe_gitops_command(command: str) -> bool:
+    """Check if command is explicitly safe (read-only)."""
+    safe_patterns = SAFE_KUBECTL_COMMANDS + SAFE_FLUX_COMMANDS + SAFE_HELM_COMMANDS
+    for pattern in safe_patterns:
+        if re.search(pattern, command, re.IGNORECASE):
+            return True
+    return False
+
+
+def is_forbidden_gitops_command(command: str) -> bool:
+    """Check if command is forbidden (modifies cluster state)."""
+    forbidden_patterns = (
+        FORBIDDEN_KUBECTL_COMMANDS +
+        FORBIDDEN_FLUX_COMMANDS +
+        FORBIDDEN_HELM_COMMANDS
+    )
+    for pattern in forbidden_patterns:
+        if re.search(pattern, command, re.IGNORECASE):
+            return True
+    return False
+
+
+def validate_gitops_workflow(
+    command: str,
+    agent_type: Optional[str] = None
+) -> GitOpsValidationResult:
+    """
+    Validate command against GitOps security principles.
+
+    Args:
+        command: Shell command to validate
+        agent_type: Optional agent type for stricter validation
+
+    Returns:
+        GitOpsValidationResult with status and suggestions
+    """
+    # Check if command is explicitly safe
+    if is_safe_gitops_command(command):
+        return GitOpsValidationResult(
+            allowed=True,
+            reason="Read-only operation - safe to execute",
+        )
+
+    # Check if command is forbidden
+    if is_forbidden_gitops_command(command):
+        suggestions = []
+
+        # Provide specific suggestions based on command type
+        if "kubectl apply" in command and "--dry-run" not in command:
+            suggestions.extend([
+                "Use: kubectl apply --dry-run=client -f <file>",
+                "Create manifests in gitops repository first",
+                "Commit changes and let Flux CD reconcile"
+            ])
+        elif "flux reconcile" in command and "--dry-run" not in command:
+            suggestions.extend([
+                "Use: flux reconcile <resource> --dry-run",
+                "Follow GitOps workflow: commit -> push -> automatic reconciliation"
+            ])
+        elif "helm install" in command or "helm upgrade" in command:
+            suggestions.extend([
+                "Use: helm template or helm upgrade --dry-run",
+                "Deploy via HelmRelease manifests in gitops repository"
+            ])
+        else:
+            suggestions.append("Use read-only commands or --dry-run alternatives")
+
+        return GitOpsValidationResult(
+            allowed=False,
+            reason="Command violates GitOps principles - modifies cluster state directly",
+            severity="critical",
+            suggestions=suggestions,
+        )
+
+    # For gitops-operator agent, be extra strict
+    if agent_type == "gitops-operator":
+        if ("apply" in command or "create" in command) and "--dry-run" not in command:
+            return GitOpsValidationResult(
+                allowed=False,
+                reason="GitOps operator must use --dry-run for all apply operations",
+                severity="high",
+                suggestions=["Add --dry-run=client flag to command"],
+            )
+
+    # Default: allow but warn about unclear intent
+    return GitOpsValidationResult(
+        allowed=True,
+        reason="Command not explicitly validated - proceed with caution",
+        severity="warning",
+        suggestions=["Verify command follows GitOps principles"],
+    )