agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/cli/output.py

@@ -0,0 +1,192 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Terminal output helpers for the Agent OS CLI.
+
+Provides ANSI colour formatting, error/warning formatters, and the
+module-level ``Colors`` singleton used across all CLI sub-commands.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import pathlib
+import sys
+import traceback
+
+logger = logging.getLogger(__name__)
+
+# ============================================================================
+# Terminal Colour Support
+# ============================================================================
+
+
+def supports_color() -> bool:
+    """Check if terminal supports colors."""
+    if os.environ.get('NO_COLOR') or os.environ.get('CI'):
+        return False
+    return sys.stdout.isatty()
+
+
+class Colors:
+    """ANSI color codes for terminal output.
+
+    Uses instance attributes so that ``disable()`` does not mutate shared
+    class state.  A module-level singleton is created below; import and use
+    that instead of the class directly.
+    """
+
+    _DEFAULTS: dict[str, str] = {
+        'RED': '\033[91m',
+        'GREEN': '\033[92m',
+        'YELLOW': '\033[93m',
+        'BLUE': '\033[94m',
+        'MAGENTA': '\033[95m',
+        'CYAN': '\033[96m',
+        'WHITE': '\033[97m',
+        'BOLD': '\033[1m',
+        'DIM': '\033[2m',
+        'RESET': '\033[0m',
+    }
+
+    def __init__(self, enabled: bool | None = None) -> None:
+        if enabled is None:
+            enabled = supports_color()
+        self._enabled = enabled
+        self._apply(enabled)
+
+    def _apply(self, enabled: bool) -> None:
+        for name, code in self._DEFAULTS.items():
+            setattr(self, name, code if enabled else '')
+
+    def disable(self) -> None:
+        """Disable colors on *this* instance."""
+        self._enabled = False
+        self._apply(False)
+
+    def enable(self) -> None:
+        """Enable colors on *this* instance."""
+        self._enabled = True
+        self._apply(True)
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+
+# Module-level singleton – every import shares this instance.
+Colors = Colors()  # type: ignore[misc]
+
+
+# ============================================================================
+# Output Format
+# ============================================================================
+
+
+def get_output_format(args: argparse.Namespace) -> str:
+    """Determine the output format from CLI arguments."""
+    if getattr(args, "json", False):
+        return "json"
+    return getattr(args, "format", "text")
+
+
+def get_config_path(args_path: str | None = None) -> "pathlib.Path":
+    """Resolve the config path from args or AGENTOS_CONFIG env var."""
+    from pathlib import Path as _Path
+
+    if args_path:
+        return _Path(args_path)
+    env_config = os.environ.get("AGENTOS_CONFIG")
+    if env_config:
+        return _Path(env_config)
+    return _Path(".")
+
+
+# ============================================================================
+# CLI Error Formatting
+# ============================================================================
+
+DOCS_URL = "https://github.com/microsoft/agent-governance-toolkit/blob/main/docs"
+
+AVAILABLE_POLICIES = ("strict", "permissive", "audit")
+
+
+def _difflib_best_match(word: str, candidates: list[str]) -> str | None:
+    """Return the closest match from *candidates*, or ``None``."""
+    import difflib
+
+    matches = difflib.get_close_matches(word, candidates, n=1, cutoff=0.5)
+    return matches[0] if matches else None
+
+
+def format_error(message: str, suggestion: str | None = None,
+                 docs_path: str | None = None) -> str:
+    """Return a colorized error string with an optional suggestion and docs link."""
+    parts = [f"{Colors.RED}{Colors.BOLD}Error:{Colors.RESET} {message}"]
+    if suggestion:
+        parts.append(f"  {Colors.GREEN}💡 Suggestion:{Colors.RESET} {suggestion}")
+    if docs_path:
+        parts.append(f"  {Colors.DIM}📖 Docs: {DOCS_URL}/{docs_path}{Colors.RESET}")
+    return "\n".join(parts)
+
+
+def handle_cli_error(e: Exception, args: argparse.Namespace) -> int:
+    """Centralized error handler for Agent OS CLI."""
+    # Sanitize exception message to avoid leaking internal details
+    is_known_error = isinstance(e, (FileNotFoundError, ValueError, PermissionError))
+    error_msg = "A file, value, or permission error occurred." if is_known_error else "An internal error occurred."
+
+    if getattr(args, "json", False) or (hasattr(args, "format") and args.format == "json"):
+        print(json.dumps({
+            "status": "error",
+            "message": error_msg,
+            "error_type": "ValidationError" if is_known_error else "InternalError"
+        }, indent=2))
+    else:
+        print(format_error(error_msg))
+        if os.environ.get("AGENTOS_DEBUG"):
+            traceback.print_exc()
+    return 1
+
+
+def handle_missing_config(path: str = ".") -> str:
+    """Error message for a missing ``.agents/`` config directory."""
+    return format_error(
+        f"Config directory not found: {path}/.agents/",
+        suggestion="Did you mean to create one? Run: agentos init",
+        docs_path="getting-started.md",
+    )
+
+
+def handle_invalid_policy(name: str) -> str:
+    """Error message for an unrecognised policy template name."""
+    available = ", ".join(AVAILABLE_POLICIES)
+    suggestion = f"Available policies: {available}"
+    match = _difflib_best_match(name, list(AVAILABLE_POLICIES))
+    if match:
+        suggestion += f". Did you mean '{match}'?"
+    return format_error(
+        f"Unknown policy template: '{name}'",
+        suggestion=suggestion,
+        docs_path="security-spec.md",
+    )
+
+
+def handle_missing_dependency(package: str, extra: str = "") -> str:
+    """Error message when an optional dependency is missing."""
+    install_cmd = f"pip install agent-os-kernel[{extra}]" if extra else f"pip install {package}"
+    return format_error(
+        f"Required package not installed: {package}",
+        suggestion=f"Install with: {install_cmd}",
+        docs_path="installation.md",
+    )
+
+
+def handle_connection_error(host: str, port: int) -> str:
+    """Error message for a connection failure."""
+    return format_error(
+        f"Could not connect to {host}:{port}",
+        suggestion=f"Check that the service is running on {host}:{port}",
+    )

agent_os/cli/policy_checker.py

@@ -0,0 +1,330 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Local-first code policy checker for the Agent OS CLI.
+
+Defines ``PolicyViolation``, ``PolicyChecker``, and the helper
+``load_cli_policy_rules()`` used by the ``agentos check`` and
+``agentos review`` commands.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import warnings
+from pathlib import Path
+from typing import Any
+
+
+# ============================================================================
+# PolicyViolation
+# ============================================================================
+
+
+class PolicyViolation:
+    """Represents a policy violation found in code."""
+
+    def __init__(self, line: int, code: str, violation: str, policy: str,
+                 severity: str = 'high', suggestion: str | None = None) -> None:
+        self.line = line
+        self.code = code
+        self.violation = violation
+        self.policy = policy
+        self.severity = severity
+        self.suggestion = suggestion
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert violation to dictionary for JSON output."""
+        return {
+            "line": self.line,
+            "code": self.code,
+            "violation": self.violation,
+            "policy": self.policy,
+            "severity": self.severity,
+            "suggestion": self.suggestion
+        }
+
+
+# ============================================================================
+# Rule Loading
+# ============================================================================
+
+
+def load_cli_policy_rules(path: str) -> list[dict[str, Any]]:
+    """Load CLI policy checker rules from a YAML file.
+
+    Args:
+        path: Path to a YAML file with a ``rules`` section.
+
+    Returns:
+        List of rule dicts suitable for ``PolicyChecker``.
+
+    Raises:
+        FileNotFoundError: If the config file does not exist.
+        ValueError: If the YAML is missing the ``rules`` section.
+    """
+    import yaml
+
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"CLI policy rules config not found: {path}")
+
+    with open(path, "r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh.read())
+
+    if not isinstance(data, dict) or "rules" not in data:
+        raise ValueError(f"YAML file must contain a 'rules' section: {path}")
+
+    return data["rules"]
+
+
+# ============================================================================
+# PolicyChecker
+# ============================================================================
+
+
+class PolicyChecker:
+    """Local-first code policy checker."""
+
+    def __init__(self, rules: list[dict[str, Any]] | None = None) -> None:
+        if rules is not None:
+            self.rules = rules
+        else:
+            self.rules = self._load_default_rules()
+
+    def _load_default_rules(self) -> list[dict[str, Any]]:
+        """Load default safety rules.
+
+        .. deprecated::
+            Uses built-in sample rules. For production use, load an explicit
+            config with ``load_cli_policy_rules()``.
+        """
+        warnings.warn(
+            "PolicyChecker._load_default_rules() uses built-in sample rules that may not "
+            "cover all security violations. For production use, load an "
+            "explicit config with load_cli_policy_rules(). "
+            "See examples/policies/cli-security-rules.yaml for a sample configuration.",
+            stacklevel=2,
+        )
+        return [
+            # Destructive SQL
+            {
+                'name': 'block-destructive-sql',
+                'pattern': r'\bDROP\s+(TABLE|DATABASE|SCHEMA|INDEX)\s+',
+                'message': 'Destructive SQL: DROP operation detected',
+                'severity': 'critical',
+                'suggestion': '-- Consider using soft delete or archiving instead',
+                'languages': ['sql', 'python', 'javascript', 'typescript', 'php', 'ruby', 'java']
+            },
+            {
+                'name': 'block-destructive-sql',
+                'pattern': r'\bDELETE\s+FROM\s+\w+\s*(;|$|WHERE\s+1\s*=\s*1)',
+                'message': 'Destructive SQL: DELETE without proper WHERE clause',
+                'severity': 'critical',
+                'suggestion': '-- Add a specific WHERE clause to limit deletion',
+                'languages': ['sql', 'python', 'javascript', 'typescript', 'php', 'ruby', 'java']
+            },
+            {
+                'name': 'block-destructive-sql',
+                'pattern': r'\bTRUNCATE\s+TABLE\s+',
+                'message': 'Destructive SQL: TRUNCATE operation detected',
+                'severity': 'critical',
+                'suggestion': '-- Consider archiving data before truncating',
+                'languages': ['sql', 'python', 'javascript', 'typescript', 'php', 'ruby', 'java']
+            },
+            # File deletion
+            {
+                'name': 'block-file-deletes',
+                'pattern': r'\brm\s+(-rf|-fr|--recursive\s+--force)\s+',
+                'message': 'Destructive operation: Recursive force delete (rm -rf)',
+                'severity': 'critical',
+                'suggestion': '# Use safer alternatives like trash-cli or move to backup',
+                'languages': ['bash', 'shell', 'sh', 'zsh']
+            },
+            {
+                'name': 'block-file-deletes',
+                'pattern': r'\bshutil\s*\.\s*rmtree\s*\(',
+                'message': 'Recursive directory deletion (shutil.rmtree)',
+                'severity': 'high',
+                'suggestion': '# Consider using send2trash for safer deletion',
+                'languages': ['python']
+            },
+            {
+                'name': 'block-file-deletes',
+                'pattern': r'\bos\s*\.\s*(remove|unlink|rmdir)\s*\(',
+                'message': 'File/directory deletion operation detected',
+                'severity': 'medium',
+                'languages': ['python']
+            },
+            # Secret exposure
+            {
+                'name': 'block-secret-exposure',
+                'pattern': r'(api[_-]?key|apikey|api[_-]?secret)\s*[=:]\s*["\'][a-zA-Z0-9_-]{20,}["\']',
+                'message': 'Hardcoded API key detected',
+                'severity': 'critical',
+                'suggestion': '# Use environment variables: os.environ["API_KEY"]',
+                'languages': None  # All languages
+            },
+            {
+                'name': 'block-secret-exposure',
+                'pattern': r'(password|passwd|pwd)\s*[=:]\s*["\'][^"\']+["\']',
+                'message': 'Hardcoded password detected',
+                'severity': 'critical',
+                'suggestion': '# Use environment variables or a secrets manager',
+                'languages': None
+            },
+            {
+                'name': 'block-secret-exposure',
+                'pattern': r'AKIA[0-9A-Z]{16}',
+                'message': 'AWS Access Key ID detected in code',
+                'severity': 'critical',
+                'languages': None
+            },
+            {
+                'name': 'block-secret-exposure',
+                'pattern': r'-----BEGIN\s+(RSA|DSA|EC|OPENSSH)\s+PRIVATE\s+KEY-----',
+                'message': 'Private key detected in code',
+                'severity': 'critical',
+                'languages': None
+            },
+            {
+                'name': 'block-secret-exposure',
+                'pattern': r'gh[pousr]_[A-Za-z0-9_]{36,}',
+                'message': 'GitHub token detected in code',
+                'severity': 'critical',
+                'languages': None
+            },
+            # Privilege escalation
+            {
+                'name': 'block-privilege-escalation',
+                'pattern': r'\bsudo\s+',
+                'message': 'Privilege escalation: sudo command detected',
+                'severity': 'high',
+                'suggestion': '# Avoid sudo in scripts - run with appropriate permissions',
+                'languages': ['bash', 'shell', 'sh', 'zsh']
+            },
+            {
+                'name': 'block-privilege-escalation',
+                'pattern': r'\bchmod\s+777\s+',
+                'message': 'Insecure permissions: chmod 777 detected',
+                'severity': 'high',
+                'suggestion': '# Use more restrictive permissions: chmod 755 or chmod 644',
+                'languages': ['bash', 'shell', 'sh', 'zsh']
+            },
+            # Code injection
+            {
+                'name': 'block-arbitrary-exec',
+                'pattern': r'\beval\s*\(',
+                'message': 'Code injection risk: eval() usage detected',
+                'severity': 'high',
+                'suggestion': '# Remove eval() and use safer alternatives',
+                'languages': ['python', 'javascript', 'typescript', 'php', 'ruby']
+            },
+            {
+                'name': 'block-arbitrary-exec',
+                'pattern': r'\bos\s*\.\s*system\s*\([^)]*(\+|%|\.format|f["\'])',
+                'message': 'Command injection risk: os.system with dynamic input',
+                'severity': 'critical',
+                'suggestion': '# Use subprocess with shell=False and proper argument handling',
+                'languages': ['python']
+            },
+            {
+                'name': 'block-arbitrary-exec',
+                'pattern': r'\bexec\s*\(',
+                'message': 'Code injection risk: exec() usage detected',
+                'severity': 'high',
+                'suggestion': '# Remove exec() and use safer alternatives',
+                'languages': ['python']
+            },
+            # SQL injection
+            {
+                'name': 'block-sql-injection',
+                'pattern': r'["\']\s*\+\s*[^"\']+\s*\+\s*["\'].*(?:SELECT|INSERT|UPDATE|DELETE)',
+                'message': 'SQL injection risk: String concatenation in SQL query',
+                'severity': 'high',
+                'suggestion': '# Use parameterized queries instead',
+                'languages': ['python', 'javascript', 'typescript', 'php', 'ruby', 'java']
+            },
+            # XSS
+            {
+                'name': 'block-xss',
+                'pattern': r'\.innerHTML\s*=',
+                'message': 'XSS risk: innerHTML assignment detected',
+                'severity': 'medium',
+                'suggestion': '// Use textContent or a sanitization library',
+                'languages': ['javascript', 'typescript']
+            },
+        ]
+
+    def _get_language(self, filepath: str) -> str:
+        """Detect language from file extension."""
+        ext_map = {
+            '.py': 'python',
+            '.js': 'javascript',
+            '.ts': 'typescript',
+            '.jsx': 'javascript',
+            '.tsx': 'typescript',
+            '.sql': 'sql',
+            '.sh': 'shell',
+            '.bash': 'bash',
+            '.zsh': 'zsh',
+            '.php': 'php',
+            '.rb': 'ruby',
+            '.java': 'java',
+            '.cs': 'csharp',
+            '.go': 'go',
+        }
+        ext = Path(filepath).suffix.lower()
+        return ext_map.get(ext, 'unknown')
+
+    def check_file(self, filepath: str) -> list[PolicyViolation]:
+        """Check a file for policy violations."""
+        path = Path(filepath)
+        if not path.exists():
+            raise FileNotFoundError(f"File not found: {filepath}")
+
+        language = self._get_language(filepath)
+        content = path.read_text(encoding='utf-8', errors='ignore')
+        lines = content.split('\n')
+
+        violations = []
+
+        for rule in self.rules:
+            # Check language filter
+            if rule['languages'] and language not in rule['languages']:
+                continue
+
+            pattern = re.compile(rule['pattern'], re.IGNORECASE)
+
+            for i, line in enumerate(lines, 1):
+                if pattern.search(line):
+                    violations.append(PolicyViolation(
+                        line=i,
+                        code=line.strip(),
+                        violation=rule['message'],
+                        policy=rule['name'],
+                        severity=rule['severity'],
+                        suggestion=rule.get('suggestion')
+                    ))
+
+        return violations
+
+    def check_staged_files(self) -> dict[str, list[PolicyViolation]]:
+        """Check all staged git files for violations."""
+        try:
+            result = subprocess.run(
+                ['git', 'diff', '--cached', '--name-only'],
+                capture_output=True, text=True, check=True
+            )
+            files = [f for f in result.stdout.strip().split('\n') if f]
+        except subprocess.CalledProcessError:
+            return {}
+
+        all_violations = {}
+        for filepath in files:
+            if Path(filepath).exists():
+                violations = self.check_file(filepath)
+                if violations:
+                    all_violations[filepath] = violations
+
+        return all_violations

agent_os/compat.py

@@ -0,0 +1,74 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Graceful degradation helpers for optional toolkit dependencies.
+
+Provides no-op fallbacks so consumers can optionally depend on the
+toolkit without try/except import boilerplate.
+
+Usage::
+
+    from agent_os.compat import PolicyEvaluator, get_evaluator
+
+    # Real class if agent-os-kernel installed, no-op otherwise.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+try:
+    from agent_os.policies.evaluator import PolicyEvaluator as _RealEvaluator
+
+    TOOLKIT_AVAILABLE = True
+except ImportError:
+    TOOLKIT_AVAILABLE = False
+    _RealEvaluator = None  # type: ignore[assignment, misc]
+
+
+class _AllowDecision:
+    allowed = True
+    reason = "no-op"
+    matched_rule = None
+
+
+class NoOpPolicyEvaluator:
+    """No-op policy evaluator — allows all actions."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        logger.debug("NoOpPolicyEvaluator: toolkit not installed, all actions allowed")
+
+    def evaluate(self, *args: Any, **kwargs: Any) -> _AllowDecision:
+        return _AllowDecision()
+
+    def load_policies(self, *args: Any, **kwargs: Any) -> None:
+        pass
+
+    def add_backend(self, *args: Any, **kwargs: Any) -> None:
+        pass
+
+
+class NoOpGovernanceMiddleware:
+    """No-op governance middleware — passes all calls through."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        logger.debug("NoOpGovernanceMiddleware: toolkit not installed")
+
+    def __call__(self, func: Any) -> Any:
+        return func
+
+    def wrap(self, func: Any) -> Any:
+        return func
+
+
+def get_evaluator(**kwargs: Any) -> Any:
+    """Get a PolicyEvaluator if available, otherwise a no-op."""
+    if TOOLKIT_AVAILABLE and _RealEvaluator is not None:
+        return _RealEvaluator(**kwargs)
+    return NoOpPolicyEvaluator(**kwargs)
+
+
+PolicyEvaluator = _RealEvaluator if TOOLKIT_AVAILABLE else NoOpPolicyEvaluator  # type: ignore[assignment]
+GovernanceMiddleware = NoOpGovernanceMiddleware