cycode 3.15.3.dev8__tar.gz → 3.15.4.dev2__tar.gz

{cycode-3.15.3.dev8 → cycode-3.15.4.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cycode
-Version: 3.15.3.dev8
+Version: 3.15.4.dev2
 Summary: Boost security in your dev lifecycle via SAST, SCA, Secrets & IaC scanning.
 License-Expression: MIT
 License-File: LICENCE
@@ -34,6 +34,8 @@ Requires-Dist: pyyaml (>=6.0,<7.0)
 Requires-Dist: requests (>=2.32.4,<3.0)
 Requires-Dist: rich (>=13.9.4,<14)
 Requires-Dist: tenacity (>=9.0.0,<9.1.0)
+Requires-Dist: tomli (>=2.0.0,<3.0.0) ; python_version < "3.11"
+Requires-Dist: tomli-w (>=1.0.0,<2.0.0)
 Requires-Dist: typer (>=0.15.3,<0.16.0)
 Requires-Dist: urllib3 (>=2.4.0,<3.0.0)
 Project-URL: Repository, https://github.com/cycodehq/cycode-cli

cycode-3.15.4.dev2/cycode/__init__.py

@@ -0,0 +1 @@
+__version__ = '3.15.4.dev2'  # DON'T TOUCH. Placeholder. Will be filled automatically on poetry build from Git Tag

cycode-3.15.4.dev2/cycode/cli/apps/ai_guardrails/command_utils.py

@@ -0,0 +1,25 @@
+"""Common utilities for AI guardrails commands."""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def validate_scope(scope: str, allowed_scopes: tuple[str, ...] = ('user', 'repo')) -> None:
+    """Validate scope parameter."""
+    if scope not in allowed_scopes:
+        scopes_list = ', '.join(f'"{s}"' for s in allowed_scopes)
+        console.print(f'[red]Error:[/] Invalid scope. Use {scopes_list}.', style='bold red')
+        raise typer.Exit(1)
+
+
+def resolve_repo_path(scope: str, repo_path: Optional[Path]) -> Optional[Path]:
+    """Default repo_path to cwd for 'repo' scope; leave None for 'user' scope."""
+    if scope == 'repo' and repo_path is None:
+        return Path(os.getcwd())
+    return repo_path

cycode-3.15.4.dev2/cycode/cli/apps/ai_guardrails/consts.py

@@ -0,0 +1,23 @@
+"""Shared constants and policy/mode enums for AI guardrails."""
+
+from enum import Enum
+
+
+class PolicyMode(str, Enum):
+    """Policy enforcement mode for global mode and per-feature actions."""
+
+    BLOCK = 'block'
+    WARN = 'warn'
+
+
+class InstallMode(str, Enum):
+    """Installation mode for ai-guardrails install command."""
+
+    REPORT = 'report'
+    BLOCK = 'block'
+
+
+# Base CLI commands invoked from installed hooks. IDE classes append --ide flags
+# (and any other suffix) on top of these.
+CYCODE_SCAN_PROMPT_COMMAND = 'cycode ai-guardrails scan'
+CYCODE_SESSION_START_COMMAND = 'cycode ai-guardrails session-start'

cycode-3.15.4.dev2/cycode/cli/apps/ai_guardrails/hooks_manager.py

@@ -0,0 +1,253 @@
+"""Hooks manager for AI guardrails.
+
+Generic install/uninstall/status logic. All IDE-specific concerns (settings
+paths, hooks template shape) live on the `IDE` instance; this module is
+agent-agnostic.
+"""
+
+import copy
+import json
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from cycode.cli.apps.ai_guardrails.consts import PolicyMode
+from cycode.cli.apps.ai_guardrails.ides.base import IDE
+from cycode.cli.apps.ai_guardrails.scan.consts import DEFAULT_POLICY, POLICY_FILE_NAME
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails Hooks')
+
+
+_CYCODE_COMMAND_MARKERS = ('cycode ai-guardrails',)
+
+
+def _is_cycode_command(command: str) -> bool:
+    return any(marker in command for marker in _CYCODE_COMMAND_MARKERS)
+
+
+def is_cycode_hook_entry(entry: dict) -> bool:
+    """True if any hook inside ``entry`` is owned by Cycode."""
+    command = entry.get('command', '')
+    if _is_cycode_command(command):
+        return True
+
+    for hook in entry.get('hooks', []):
+        if isinstance(hook, dict) and _is_cycode_command(hook.get('command', '')):
+            return True
+
+    return False
+
+
+def _strip_cycode_from_entry(entry: dict) -> Optional[dict]:
+    """Remove Cycode hooks from ``entry`` and return the remainder.
+
+    Returns ``None`` when nothing useful remains (Cursor-flat Cycode entry, or
+    every nested hook was Cycode). Non-Cycode hooks co-located in the same
+    entry are preserved.
+    """
+    # Cursor format: the entry itself IS a single hook command.
+    if 'command' in entry and 'hooks' not in entry:
+        return None if _is_cycode_command(entry.get('command', '')) else entry
+
+    # Claude Code / Codex format: nested `hooks` list inside the entry.
+    nested = entry.get('hooks')
+    if isinstance(nested, list):
+        kept = [h for h in nested if not (isinstance(h, dict) and _is_cycode_command(h.get('command', '')))]
+        if not kept:
+            return None
+        if len(kept) == len(nested):
+            return entry  # nothing Cycode-shaped inside; preserve identity
+        return {**entry, 'hooks': kept}
+
+    # Entry has neither shape we recognize — leave it alone defensively.
+    return entry
+
+
+def _load_hooks_file(hooks_path: Path) -> Optional[dict]:
+    if not hooks_path.exists():
+        return None
+    try:
+        return json.loads(hooks_path.read_text(encoding='utf-8'))
+    except Exception as e:
+        logger.debug('Failed to load hooks file', exc_info=e)
+        return None
+
+
+def _save_hooks_file(hooks_path: Path, hooks_config: dict) -> bool:
+    try:
+        hooks_path.parent.mkdir(parents=True, exist_ok=True)
+        hooks_path.write_text(json.dumps(hooks_config, indent=2), encoding='utf-8')
+        return True
+    except Exception as e:
+        logger.error('Failed to save hooks file', exc_info=e)
+        return False
+
+
+def _load_policy_dict(policy_path: Path) -> dict:
+    if not policy_path.exists():
+        return copy.deepcopy(DEFAULT_POLICY)
+    try:
+        existing = yaml.safe_load(policy_path.read_text(encoding='utf-8')) or {}
+    except Exception:
+        existing = {}
+    return {**copy.deepcopy(DEFAULT_POLICY), **existing}
+
+
+def create_policy_file(scope: str, mode: PolicyMode, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+    """Create or update the ai-guardrails.yaml policy file.
+
+    If the file already exists, only the mode field is updated; otherwise a new
+    file is created from the default policy.
+    """
+    config_dir = repo_path / '.cycode' if scope == 'repo' and repo_path else Path.home() / '.cycode'
+    policy_path = config_dir / POLICY_FILE_NAME
+
+    policy = _load_policy_dict(policy_path)
+    policy['mode'] = mode.value
+
+    try:
+        config_dir.mkdir(parents=True, exist_ok=True)
+        policy_path.write_text(yaml.dump(policy, default_flow_style=False, sort_keys=False), encoding='utf-8')
+        return True, f'AI guardrails policy ({mode.value} mode) set: {policy_path}'
+    except Exception as e:
+        logger.error('Failed to create policy file', exc_info=e)
+        return False, f'Failed to create policy file: {policy_path}'
+
+
+def install_hooks(
+    ide: IDE,
+    scope: str = 'user',
+    repo_path: Optional[Path] = None,
+    report_mode: bool = False,
+) -> tuple[bool, str]:
+    """Install Cycode AI guardrails hooks for ``ide``."""
+    hooks_path = ide.settings_path(scope, repo_path)
+
+    existing = _load_hooks_file(hooks_path) or {'version': 1, 'hooks': {}}
+    existing.setdefault('version', 1)
+    existing.setdefault('hooks', {})
+
+    rendered = ide.render_hooks_config(async_mode=report_mode)
+
+    for event, entries in rendered['hooks'].items():
+        existing['hooks'].setdefault(event, [])
+        existing['hooks'][event] = [
+            stripped for e in existing['hooks'][event] if (stripped := _strip_cycode_from_entry(e)) is not None
+        ]
+        for entry in entries:
+            existing['hooks'][event].append(entry)
+
+    if not _save_hooks_file(hooks_path, existing):
+        return False, f'Failed to install hooks to {hooks_path}'
+
+    message = f'AI guardrails hooks installed: {hooks_path}'
+
+    # IDE-specific extras (e.g. Codex enables a TOML feature flag).
+    extra_ok, extra_message = ide.post_install(scope, repo_path)
+    if not extra_ok:
+        return False, extra_message
+    if extra_message:
+        message = f'{message}\n  {extra_message}'
+
+    return True, message
+
+
+def _strip_cycode_entries(existing: dict) -> bool:
+    """Mutate ``existing`` to drop Cycode hooks (surgically). Return True if anything changed."""
+    modified = False
+    for event in list(existing.get('hooks', {}).keys()):
+        before = existing['hooks'][event]
+        after: list = []
+        for e in before:
+            stripped = _strip_cycode_from_entry(e)
+            if stripped is None:
+                modified = True
+                continue
+            if stripped is not e:
+                modified = True
+            after.append(stripped)
+        if not after:
+            del existing['hooks'][event]
+        else:
+            existing['hooks'][event] = after
+    return modified
+
+
+def _persist_uninstall(hooks_path: Path, existing: dict, modified: bool) -> tuple[bool, str]:
+    """Apply the uninstall result to disk and return ``(success, message)``."""
+    if not modified:
+        return True, 'No Cycode hooks found to remove'
+    if not existing.get('hooks'):
+        try:
+            hooks_path.unlink()
+        except Exception as e:
+            logger.debug('Failed to delete hooks file', exc_info=e)
+            return False, f'Failed to remove hooks file: {hooks_path}'
+        return True, f'Removed hooks file: {hooks_path}'
+    if not _save_hooks_file(hooks_path, existing):
+        return False, f'Failed to update hooks file: {hooks_path}'
+    return True, f'Cycode hooks removed from: {hooks_path}'
+
+
+def uninstall_hooks(ide: IDE, scope: str = 'user', repo_path: Optional[Path] = None) -> tuple[bool, str]:
+    """Remove Cycode AI guardrails hooks for ``ide``."""
+    hooks_path = ide.settings_path(scope, repo_path)
+
+    existing = _load_hooks_file(hooks_path)
+    if existing is None:
+        return True, f'No hooks file found at {hooks_path}'
+
+    modified = _strip_cycode_entries(existing)
+    file_ok, message = _persist_uninstall(hooks_path, existing, modified)
+    if not file_ok:
+        return False, message
+
+    extra_ok, extra_message = ide.post_uninstall(scope, repo_path)
+    if not extra_ok:
+        return False, extra_message
+    if extra_message:
+        message = f'{message}\n  {extra_message}'
+    return True, message
+
+
+def get_hooks_status(ide: IDE, scope: str = 'user', repo_path: Optional[Path] = None) -> dict:
+    """Return installation status of Cycode hooks for ``ide``."""
+    hooks_path = ide.settings_path(scope, repo_path)
+
+    status: dict = {
+        'scope': scope,
+        'ide': ide.name,
+        'ide_name': ide.display_name,
+        'hooks_path': str(hooks_path),
+        'file_exists': hooks_path.exists(),
+        'cycode_installed': False,
+        'hooks': {},
+    }
+
+    existing = _load_hooks_file(hooks_path)
+    if existing is None:
+        return status
+
+    has_cycode_hooks = False
+    for event in ide.hook_events:
+        # '<event>:<matcher>' filters entries to a specific tool/matcher.
+        if ':' in event:
+            actual_event, matcher_prefix = event.split(':', 1)
+            all_entries = existing.get('hooks', {}).get(actual_event, [])
+            entries = [e for e in all_entries if e.get('matcher', '').startswith(matcher_prefix)]
+        else:
+            entries = existing.get('hooks', {}).get(event, [])
+
+        cycode_entries = [e for e in entries if is_cycode_hook_entry(e)]
+        if cycode_entries:
+            has_cycode_hooks = True
+        status['hooks'][event] = {
+            'total_entries': len(entries),
+            'cycode_entries': len(cycode_entries),
+            'enabled': len(cycode_entries) > 0,
+        }
+
+    status['cycode_installed'] = has_cycode_hooks
+    return status

cycode-3.15.4.dev2/cycode/cli/apps/ai_guardrails/ides/__init__.py

@@ -0,0 +1,45 @@
+"""Registry of supported AI guardrails IDE integrations.
+
+Adding a new IDE: create `ides/<name>.py` with a subclass of `IDE`, import it
+here, and include an instance in the `IDES` tuple. Nothing else in the package
+needs to change.
+"""
+
+import typer
+
+from cycode.cli.apps.ai_guardrails.ides.base import IDE
+from cycode.cli.apps.ai_guardrails.ides.claude_code import ClaudeCode
+from cycode.cli.apps.ai_guardrails.ides.codex import Codex
+from cycode.cli.apps.ai_guardrails.ides.cursor import Cursor
+
+# Single source of truth: name → singleton instance.
+# `--ide` choices and install/uninstall/status iteration both derive from this.
+IDES: dict[str, IDE] = {ide.name: ide for ide in (Cursor(), ClaudeCode(), Codex())}
+
+# Default IDE used when `--ide` is omitted. Kept here so the value is colocated
+# with the registry; no module outside `ides/` needs to know which IDE wins.
+DEFAULT_IDE_NAME = 'cursor'
+
+
+def get_ide(name: str) -> IDE:
+    """Look up the IDE integration registered under ``name``.
+
+    Raises ``typer.BadParameter`` when the name is unknown — surfaces as a
+    user-friendly CLI error rather than a KeyError stack trace.
+    """
+    ide = IDES.get(name.lower())
+    if ide is None:
+        valid = ', '.join(IDES.keys())
+        raise typer.BadParameter(f'Unknown IDE "{name}". Supported: {valid}.')
+    return ide
+
+
+def resolve_ides(name: str) -> list[IDE]:
+    """Resolve an ``--ide`` argument to one or all IDE instances.
+
+    ``"all"`` returns every registered IDE; anything else returns a single
+    matching IDE (raising ``typer.BadParameter`` for unknown names).
+    """
+    if name.lower() == 'all':
+        return list(IDES.values())
+    return [get_ide(name)]

cycode-3.15.4.dev2/cycode/cli/apps/ai_guardrails/ides/_plugin_utils.py

@@ -0,0 +1,73 @@
+"""Shared plugin-resolution helpers for IDE integrations.
+
+Both Claude Code and Codex use the same ``<plugin>@<marketplace>`` key convention
+and emit the same telemetry shape — only the marketplace layout and manifest
+location differ. ``walk_enabled_plugins`` is the IDE-agnostic loop; each IDE
+supplies the two callables that vary (``locate_dir`` + ``read_plugin``).
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails Plugins')
+
+
+def load_plugin_json(path: Path) -> Optional[dict]:
+    """Load a JSON file inside a plugin directory; None if missing or invalid."""
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding='utf-8'))
+    except Exception as e:
+        logger.debug('Failed to load plugin file, %s', {'path': str(path)}, exc_info=e)
+        return None
+
+
+def walk_enabled_plugins(
+    plugin_entries: dict[str, Any],
+    is_enabled: Callable[[Any], bool],
+    locate_dir: Callable[[str, str], Optional[Path]],
+    read_plugin: Callable[[Path], tuple[dict, dict]],
+) -> tuple[dict, dict]:
+    """Iterate enabled plugins; merge their MCP servers and metadata.
+
+    Args:
+        plugin_entries: ``{<plugin>@<marketplace>: settings}`` map from the IDE config.
+        is_enabled: returns True if ``settings`` indicates the plugin is on
+            (e.g. ``bool(settings)`` for Claude, ``settings.get('enabled')`` for Codex).
+        locate_dir: given ``(plugin_name, marketplace)``, returns the plugin's
+            filesystem path or None if it can't be resolved.
+        read_plugin: given the plugin path, returns ``(entry_fields, servers)``:
+            ``entry_fields`` are extra metadata to attach to the inventory entry
+            (name/version/description/...), ``servers`` are MCP servers contributed.
+
+    Returns ``(merged_mcp_servers, enriched_plugins)``. Plugin keys without
+    ``@`` (or that fail to resolve to a directory) still appear in the
+    inventory with just ``{'enabled': True}`` so we don't silently drop them.
+    """
+    merged_mcp: dict = {}
+    enriched: dict = {}
+
+    for plugin_key, settings in plugin_entries.items():
+        if not is_enabled(settings):
+            continue
+
+        entry: dict = {'enabled': True}
+        enriched[plugin_key] = entry
+
+        if '@' not in plugin_key:
+            continue
+        plugin_name, marketplace = plugin_key.split('@', 1)
+
+        plugin_dir = locate_dir(plugin_name, marketplace)
+        if plugin_dir is None:
+            continue
+
+        plugin_fields, servers = read_plugin(plugin_dir)
+        entry.update(plugin_fields)
+        merged_mcp.update(servers)
+
+    return merged_mcp, enriched

cycode-3.15.4.dev2/cycode/cli/apps/ai_guardrails/ides/base.py

@@ -0,0 +1,176 @@
+"""Base abstractions for AI guardrails IDE integrations.
+
+Each AI IDE (Cursor, Claude Code, …) is represented by a subclass of `IDE`
+that consolidates every IDE-specific concern in a single module: settings file
+paths, hooks template rendering, payload parsing, response building, and any
+IDE-specific session-context lookup.
+
+Adding a new IDE is a matter of:
+  1. Subclassing `IDE` and implementing the abstract methods.
+  2. Registering the instance in `cycode/cli/apps/ai_guardrails/ides/__init__.py`.
+
+The `HookDecision` dataclass is the canonical, IDE-agnostic return type for
+event handlers; `IDE.build_hook_response` translates it into the IDE-specific
+JSON response shape that the IDE expects on stdout.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import ClassVar, Optional
+
+from cycode.cli.apps.ai_guardrails.scan.payload import AIHookPayload
+from cycode.cli.apps.ai_guardrails.scan.types import AiHookEventType
+
+
+class DecisionAction(str, Enum):
+    """Canonical decision action returned by event handlers."""
+
+    ALLOW = 'allow'
+    DENY = 'deny'
+    ASK = 'ask'
+
+
+@dataclass(frozen=True)
+class HookDecision:
+    """Canonical, IDE-agnostic decision returned by event handlers.
+
+    Carries the event type so `IDE.build_hook_response` can pick the right
+    IDE-specific response shape (Cursor's "permission" style for tool events
+    vs. "continue" style for prompts; Claude Code's "hookSpecificOutput"
+    vs. "decision: block").
+    """
+
+    action: DecisionAction
+    event_type: AiHookEventType
+    user_message: Optional[str] = None
+    agent_message: Optional[str] = None
+
+    @classmethod
+    def allow(cls, event_type: AiHookEventType) -> 'HookDecision':
+        return cls(action=DecisionAction.ALLOW, event_type=event_type)
+
+    @classmethod
+    def deny(
+        cls, event_type: AiHookEventType, user_message: str, agent_message: Optional[str] = None
+    ) -> 'HookDecision':
+        return cls(
+            action=DecisionAction.DENY,
+            event_type=event_type,
+            user_message=user_message,
+            agent_message=agent_message,
+        )
+
+    @classmethod
+    def ask(cls, event_type: AiHookEventType, user_message: str, agent_message: Optional[str] = None) -> 'HookDecision':
+        return cls(
+            action=DecisionAction.ASK,
+            event_type=event_type,
+            user_message=user_message,
+            agent_message=agent_message,
+        )
+
+
+class IDE(ABC):
+    """Per-IDE integration. Owns every IDE-specific concern in a single module.
+
+    Subclasses declare identity via class attributes and implement the abstract
+    methods. Defaults are provided for `get_user_email` and `get_session_context`
+    so IDEs without those capabilities (e.g. no plugin system, no local
+    account file) can skip them.
+    """
+
+    # CLI value passed to --ide (e.g. 'cursor', 'claude-code').
+    name: ClassVar[str]
+    # Human-friendly name for output ('Cursor', 'Claude Code').
+    display_name: ClassVar[str]
+    # Event names for status display. Use '<event>:<matcher>' for IDEs that
+    # qualify a single hook by a sub-matcher (e.g. Claude Code's PreToolUse:Read).
+    hook_events: ClassVar[list[str]]
+
+    # --- install / status ---
+
+    @abstractmethod
+    def settings_path(self, scope: str, repo_path: Optional[Path] = None) -> Path:
+        """Return the hooks/settings file path for the given scope.
+
+        `scope` is 'user' or 'repo'. `repo_path` is required when scope == 'repo'.
+        """
+
+    @abstractmethod
+    def render_hooks_config(self, async_mode: bool = False) -> dict:
+        """Return the settings blob to merge into the IDE's settings file.
+
+        Shape is IDE-specific (Cursor uses a flat ``{event: [{command}]}`` dict;
+        Claude Code uses a nested ``{event: [{hooks: [{type, command}]}]}``
+        dict). Both share the outer ``{"hooks": ...}`` wrapper so
+        ``hooks_manager`` can treat them uniformly.
+        """
+
+    def post_install(self, scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+        """Run IDE-specific actions after the hooks file is written.
+
+        Default: no-op success. Override to perform extra setup that doesn't
+        belong in the hooks file itself — e.g. Codex enables a
+        ``[features] codex_hooks = true`` flag in its TOML config.
+
+        Returns ``(success, message)``. If ``success`` is False, the overall
+        install is considered failed.
+        """
+        return True, ''
+
+    def post_uninstall(self, scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+        """Run IDE-specific cleanup after the hooks file is removed.
+
+        Default: no-op success. Override to undo whatever ``post_install``
+        wrote outside the hooks file.
+        """
+        return True, ''
+
+    # --- runtime scan ---
+
+    @abstractmethod
+    def matches_payload(self, raw_payload: dict) -> bool:
+        """Return True if ``raw_payload`` originated from this IDE.
+
+        Prevents double-processing when an IDE forwards another IDE's hook
+        event (e.g. Cursor reading Claude Code hooks from ~/.claude/settings.json).
+        """
+
+    @abstractmethod
+    def parse_hook_payload(self, raw_payload: dict) -> AIHookPayload:
+        """Normalize a raw stdin payload into the canonical ``AIHookPayload``."""
+
+    @abstractmethod
+    def build_hook_response(self, decision: HookDecision) -> dict:
+        """Translate a canonical ``HookDecision`` into the IDE-specific JSON.
+
+        The result is what ``scan_command`` writes to stdout for the IDE to
+        act on.
+        """
+
+    # --- session lifecycle (optional; sensible defaults) ---
+
+    def build_session_payload(self, raw_payload: dict) -> AIHookPayload:
+        """Build a session-start payload from the raw stdin payload.
+
+        Default: a minimal payload tagged with this IDE's ``name``. IDEs
+        that need to enrich with transcript/version info should override.
+        """
+        return AIHookPayload(ide_provider=self.name)
+
+    def get_user_email(self) -> Optional[str]:
+        """Best-effort read of the user's email from IDE-specific config.
+
+        Default: None. Override if the IDE stores a usable account locally.
+        """
+        return None
+
+    def get_session_context(self) -> tuple[dict, dict]:
+        """Return ``(mcp_servers, enabled_plugins)`` for session-context reporting.
+
+        Default: empty dicts (no plugin system, no discoverable MCP config).
+        Override to surface MCP/plugin inventory.
+        """
+        return {}, {}