agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/credential_redactor.py

@@ -0,0 +1,224 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Credential redaction helpers for MCP audit and response safety."""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+REDACTED_PLACEHOLDER = "[REDACTED]"
+
+
+@dataclass(frozen=True)
+class CredentialPattern:
+    """A named credential detection pattern."""
+
+    name: str
+    pattern: re.Pattern[str]
+
+
+@dataclass(frozen=True)
+class CredentialMatch:
+    """A credential-like value detected in text."""
+
+    name: str
+    matched_text: str
+
+
+class CredentialRedactor:
+    """Detect and redact credential-like material in strings and nested objects.
+
+    Use this helper before persisting audit payloads or returning tool output to
+    callers. The class operates on plain strings as well as nested dictionaries,
+    lists, and tuples, replacing detected secret values with a stable
+    placeholder.
+    """
+
+    # Python's stdlib ``re`` does not support per-pattern timeouts. These
+    # patterns are kept simple and anchored to avoid pathological backtracking.
+    PATTERNS: tuple[CredentialPattern, ...] = (
+        CredentialPattern(
+            name="OpenAI API key",
+            pattern=re.compile(r"\bsk-[A-Za-z0-9][A-Za-z0-9_-]{18,}\b"),
+        ),
+        CredentialPattern(
+            name="GitHub token",
+            pattern=re.compile(r"\b(?:ghp|ghs)_[A-Za-z0-9]{20,}\b"),
+        ),
+        CredentialPattern(
+            name="AWS access key",
+            pattern=re.compile(r"\bAKIA[A-Z0-9]{16}\b"),
+        ),
+        CredentialPattern(
+            name="Azure key",
+            pattern=re.compile(
+                r"(?i)(?:accountkey|sharedaccesskey|azure[_-]?key)\s*[:=]\s*[A-Za-z0-9+/=]{20,}"
+            ),
+        ),
+        CredentialPattern(
+            name="Bearer token",
+            pattern=re.compile(r"\bBearer\s+[A-Za-z0-9._\-+/=]{16,}\b"),
+        ),
+        CredentialPattern(
+            name="PEM private key",
+            pattern=re.compile(
+                r"-----BEGIN\s+(?P<label>(?:RSA\s+|EC\s+|OPENSSH\s+)?PRIVATE\s+KEY)-----"
+                r"[\s\S]*?"
+                r"-----END\s+(?P=label)-----",
+                re.DOTALL,
+            ),
+        ),
+        CredentialPattern(
+            name="Connection string secret",
+            pattern=re.compile(
+                r"(?i)\b(?:password|pwd|accountkey|sharedaccesssignature)\s*=\s*[^;\s]{4,}"
+            ),
+        ),
+        CredentialPattern(
+            name="Basic auth secret",
+            pattern=re.compile(
+                r"(?i)(?:\bBasic\s+[A-Za-z0-9+/=]{8,}\b|\b[a-z][a-z0-9+.-]*://[^/\s:@]+:[^@\s/]+@)"
+            ),
+        ),
+        CredentialPattern(
+            name="JWT",
+            pattern=re.compile(r"\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9._-]{6,}\.[A-Za-z0-9._-]{6,}\b"),
+        ),
+        CredentialPattern(
+            name="Generic API secret",
+            pattern=re.compile(
+                r"(?i)\b(?:api[_-]?key|client[_-]?secret|secret|token)\b\s*[:=]\s*['\"]?[^\s'\";]{6,}"
+            ),
+        ),
+    )
+
+    @classmethod
+    def redact(cls, value: str | None) -> str:
+        """Redact credential-like values from a string.
+
+        Args:
+            value: String content that may contain credential-like material.
+
+        Returns:
+            A string with each detected credential replaced by
+            ``REDACTED_PLACEHOLDER``. Empty input returns an empty string.
+        """
+        if not value:
+            return ""
+
+        result = value
+        redaction_count = 0
+        for credential_pattern in cls.PATTERNS:
+            updated, count = credential_pattern.pattern.subn(REDACTED_PLACEHOLDER, result)
+            if count:
+                redaction_count += count
+                result = updated
+
+        if redaction_count:
+            logger.info("Credential redaction applied to %s value(s)", redaction_count)
+
+        return result
+
+    @classmethod
+    def redact_mapping(cls, mapping: dict[str, Any] | None) -> dict[str, Any]:
+        """Redact all nested values in a mapping.
+
+        Args:
+            mapping: A possibly nested mapping containing strings, lists,
+                tuples, or dictionaries.
+
+        Returns:
+            A new mapping with nested strings redacted recursively. Empty input
+            returns an empty dictionary.
+        """
+        if not mapping:
+            return {}
+        return {key: cls.redact_data_structure(value) for key, value in mapping.items()}
+
+    @classmethod
+    def redact_dictionary(cls, mapping: dict[str, Any] | None) -> dict[str, Any]:
+        """Compatibility alias for dictionary redaction.
+
+        Args:
+            mapping: Dictionary-like content to redact.
+
+        Returns:
+            The redacted mapping produced by :meth:`redact_mapping`.
+        """
+        return cls.redact_mapping(mapping)
+
+    @classmethod
+    def redact_data_structure(cls, value: Any) -> Any:
+        """Recursively redact nested strings in dicts, lists, and tuples.
+
+        Args:
+            value: Any Python value that may contain nested strings.
+
+        Returns:
+            A value of the same general shape with strings redacted in place of
+            their original secret-bearing content.
+        """
+        if isinstance(value, str):
+            return cls.redact(value)
+        if isinstance(value, dict):
+            return {key: cls.redact_data_structure(item) for key, item in value.items()}
+        if isinstance(value, list):
+            return [cls.redact_data_structure(item) for item in value]
+        if isinstance(value, tuple):
+            return tuple(cls.redact_data_structure(item) for item in value)
+        return value
+
+    @classmethod
+    def contains_credentials(cls, value: str | None) -> bool:
+        """Return whether a string contains any known credential pattern.
+
+        Args:
+            value: String content to inspect.
+
+        Returns:
+            ``True`` when at least one credential pattern matches, otherwise
+            ``False``.
+        """
+        return bool(cls.find_matches(value))
+
+    @classmethod
+    def detect_credential_types(cls, value: str | None) -> list[str]:
+        """Return the names of detected credential patterns.
+
+        Args:
+            value: String content to inspect.
+
+        Returns:
+            A de-duplicated list of credential type labels in detection order.
+        """
+        return list(dict.fromkeys(match.name for match in cls.find_matches(value)))
+
+    @classmethod
+    def find_matches(cls, value: str | None) -> list[CredentialMatch]:
+        """Return all credential-like matches found in a string.
+
+        Args:
+            value: String content to inspect.
+
+        Returns:
+            A list of ``CredentialMatch`` records describing each detected
+            credential-like span. Empty input returns an empty list.
+        """
+        if not value:
+            return []
+
+        matches: list[CredentialMatch] = []
+        for credential_pattern in cls.PATTERNS:
+            for match in credential_pattern.pattern.finditer(value):
+                matches.append(
+                    CredentialMatch(
+                        name=credential_pattern.name,
+                        matched_text=match.group(0),
+                    )
+                )
+        return matches

agent_os/diff_policy.py

@@ -0,0 +1,89 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""DiffPolicy rule type for git change scope enforcement.
+
+Enforces constraints on agent-authored code changes:
+file count limits, line count limits, and path restrictions.
+
+Example::
+
+    policy = DiffPolicy(max_files=20, max_lines=400, blocked_paths=["*.env", "secrets/**"])
+    result = policy.evaluate(changed_files)
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DiffFile:
+    """A file in a diff."""
+
+    path: str
+    additions: int = 0
+    deletions: int = 0
+
+
+@dataclass
+class DiffPolicyResult:
+    """Result of evaluating a diff against policy."""
+
+    allowed: bool
+    violations: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DiffPolicy:
+    """Policy rules for git change scope enforcement.
+
+    Attributes:
+        max_files: Maximum number of files changed.
+        max_lines: Maximum total lines changed (additions + deletions).
+        allowed_paths: Glob patterns for allowed file paths. Empty = all allowed.
+        blocked_paths: Glob patterns for blocked file paths.
+    """
+
+    max_files: int | None = None
+    max_lines: int | None = None
+    allowed_paths: list[str] = field(default_factory=list)
+    blocked_paths: list[str] = field(default_factory=list)
+
+    def evaluate(self, files: list[DiffFile]) -> DiffPolicyResult:
+        """Evaluate a set of changed files against this policy.
+
+        Args:
+            files: List of DiffFile objects representing the changes.
+
+        Returns:
+            DiffPolicyResult with allowed status and any violations.
+        """
+        violations = []
+
+        # Check file count
+        if self.max_files is not None and len(files) > self.max_files:
+            violations.append(f"files: {len(files)}/{self.max_files}")
+
+        # Check total lines
+        if self.max_lines is not None:
+            total_lines = sum(f.additions + f.deletions for f in files)
+            if total_lines > self.max_lines:
+                violations.append(f"lines: {total_lines}/{self.max_lines}")
+
+        # Check path restrictions
+        for f in files:
+            # Blocked paths
+            for pattern in self.blocked_paths:
+                if fnmatch.fnmatch(f.path, pattern):
+                    violations.append(f"blocked: {f.path} matches {pattern}")
+
+            # Allowed paths (if set, file must match at least one)
+            if self.allowed_paths:
+                if not any(fnmatch.fnmatch(f.path, p) for p in self.allowed_paths):
+                    violations.append(f"not_allowed: {f.path}")
+
+        return DiffPolicyResult(
+            allowed=len(violations) == 0,
+            violations=violations,
+        )

agent_os/egress_policy.py

@@ -0,0 +1,159 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Network egress policy enforcement for MCP gateway.
+
+Provides domain-level egress control so that agent tool calls can only
+reach pre-approved external endpoints.  Wildcard domains are supported
+(e.g. ``*.openai.com`` matches ``api.openai.com``).
+"""
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from typing import Optional
+from urllib.parse import urlparse
+
+
+@dataclass
+class EgressRule:
+    """A single egress control rule."""
+
+    domain: str
+    ports: list[int] = field(default_factory=lambda: [443])
+    protocol: str = "tcp"
+    action: str = "allow"
+
+    def __post_init__(self) -> None:
+        if self.action not in ("allow", "deny"):
+            raise ValueError(f"action must be 'allow' or 'deny', got {self.action!r}")
+        if self.protocol not in ("tcp", "udp"):
+            raise ValueError(f"protocol must be 'tcp' or 'udp', got {self.protocol!r}")
+
+    def matches(self, hostname: str, port: int, protocol: str) -> bool:
+        """Return *True* if this rule matches the given endpoint."""
+        if protocol != self.protocol:
+            return False
+        if port not in self.ports:
+            return False
+        return fnmatch.fnmatch(hostname.lower(), self.domain.lower())
+
+
+@dataclass
+class EgressDecision:
+    """Result of an egress policy check."""
+
+    allowed: bool
+    matched_rule: Optional[EgressRule]
+    reason: str
+
+
+class EgressPolicy:
+    """Network egress enforcement for agent tool calls.
+
+    Rules are evaluated in insertion order; the first match wins.
+    If no rule matches, ``default_action`` is applied.
+    """
+
+    def __init__(self, default_action: str = "deny") -> None:
+        if default_action not in ("allow", "deny"):
+            raise ValueError(
+                f"default_action must be 'allow' or 'deny', got {default_action!r}"
+            )
+        self.rules: list[EgressRule] = []
+        self.default_action = default_action
+
+    def add_rule(
+        self,
+        domain: str,
+        ports: list[int],
+        protocol: str = "tcp",
+        action: str = "allow",
+    ) -> EgressRule:
+        """Create and append an :class:`EgressRule`."""
+        rule = EgressRule(
+            domain=domain, ports=ports, protocol=protocol, action=action
+        )
+        self.rules.append(rule)
+        return rule
+
+    def load_from_yaml(self, yaml_str: str) -> None:
+        """Parse a simple YAML-like egress policy and add rules.
+
+        Supported format (stdlib-only, no PyYAML dependency)::
+
+            rules:
+              - domain: "*.openai.com"
+                ports: [443]
+                protocol: tcp
+                action: allow
+        """
+        current: dict[str, str] = {}
+        for raw_line in yaml_str.splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if line == "rules:" or line == "rules":
+                continue
+            if line.startswith("- domain:"):
+                if current:
+                    self._add_from_dict(current)
+                    current = {}
+                current["domain"] = self._unquote(line.split(":", 1)[1])
+            elif line.startswith("domain:"):
+                current["domain"] = self._unquote(line.split(":", 1)[1])
+            elif line.startswith("ports:"):
+                current["ports"] = line.split(":", 1)[1].strip()
+            elif line.startswith("protocol:"):
+                current["protocol"] = self._unquote(line.split(":", 1)[1])
+            elif line.startswith("action:"):
+                current["action"] = self._unquote(line.split(":", 1)[1])
+        if current:
+            self._add_from_dict(current)
+
+    def check(
+        self, hostname: str, port: int, protocol: str = "tcp"
+    ) -> EgressDecision:
+        """Check whether an outbound connection is permitted."""
+        for rule in self.rules:
+            if rule.matches(hostname, port, protocol):
+                allowed = rule.action == "allow"
+                return EgressDecision(
+                    allowed=allowed,
+                    matched_rule=rule,
+                    reason=f"matched rule for {rule.domain} -> {rule.action}",
+                )
+        allowed = self.default_action == "allow"
+        return EgressDecision(
+            allowed=allowed,
+            matched_rule=None,
+            reason=f"no matching rule; default action is {self.default_action}",
+        )
+
+    def check_url(self, url: str) -> EgressDecision:
+        """Convenience wrapper that extracts host/port from a URL."""
+        parsed = urlparse(url)
+        hostname = parsed.hostname or ""
+        port = parsed.port
+        if port is None:
+            port = 443 if parsed.scheme == "https" else 80
+        return self.check(hostname, port)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _unquote(value: str) -> str:
+        return value.strip().strip("\"'")
+
+    @staticmethod
+    def _parse_ports(raw: str) -> list[int]:
+        raw = raw.strip().strip("[]")
+        return [int(p.strip()) for p in raw.split(",") if p.strip()]
+
+    def _add_from_dict(self, d: dict[str, str]) -> None:
+        domain = d.get("domain", "")
+        ports = self._parse_ports(d.get("ports", "[443]"))
+        protocol = d.get("protocol", "tcp")
+        action = d.get("action", "allow")
+        self.add_rule(domain, ports, protocol, action)