cycode 3.15.3.dev7__tar.gz → 3.15.4.dev1__tar.gz

{cycode-3.15.3.dev7 → cycode-3.15.4.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cycode
-Version: 3.15.3.dev7
+Version: 3.15.4.dev1
 Summary: Boost security in your dev lifecycle via SAST, SCA, Secrets & IaC scanning.
 License-Expression: MIT
 License-File: LICENCE
@@ -62,6 +62,7 @@ This guide walks you through both installation and usage.
     2. [Available Options](#available-options)
     3. [MCP Tools](#mcp-tools)
     4. [Usage Examples](#usage-examples)
+    5. [Advanced Configuration](#advanced-configuration)
 5. [Platform Command](#platform-command-beta)
     1. [Discovering Commands](#discovering-commands)
     2. [Examples](#platform-examples)
@@ -600,6 +601,38 @@ cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &
 }
 ```
 
+### Advanced Configuration 
+##### Custom Certificates and Timeouts (Proxy Environments)
+
+If your organization uses a corporate proxy or a custom CA bundle for HTTPS inspection, you need to tell Cycode CLI (and the underlying Python TLS stack) where to find the trusted certificate bundle. You can also increase the MCP tool call timeout if scans are being cut short.
+
+| Environment Variable | Description |
+|----------------------|-------------|
+| `REQUESTS_CA_BUNDLE` | Path to a custom CA bundle file (`.pem` or `.crt`). Used by the `requests` library for all HTTPS calls made by Cycode CLI. |
+| `SSL_CERT_FILE`      | Path to a custom CA bundle file. Used by Python's low-level `ssl` module. Set this alongside `REQUESTS_CA_BUNDLE` for full coverage. |
+| `MCP_TOOL_TIMEOUT`   | Timeout (in seconds) that MCP clients such as Claude and GitHub Copilot wait for a tool call to complete. Increase this if long-running scans are being cut off before they finish. |
+
+> [!TIP]
+> Set both `REQUESTS_CA_BUNDLE` and `SSL_CERT_FILE` to the same CA bundle path. `REQUESTS_CA_BUNDLE` covers the HTTP layer; `SSL_CERT_FILE` covers the lower-level TLS layer. Using only one may still cause certificate errors in some environments.
+
+Example `mcp.json` configuration with custom certificates and a longer timeout:
+
+```json
+{
+  "mcpServers": {
+    "cycode": {
+      "command": "cycode",
+      "args": ["mcp"],
+      "env": {
+        "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
+        "SSL_CERT_FILE": "/path/to/your/corporate-ca-bundle.pem",
+        "MCP_TOOL_TIMEOUT": "1800"
+      }
+    }
+  }
+}
+```
+
 > [!NOTE]
 > The MCP server requires proper Cycode CLI authentication to function. Make sure you have authenticated using `cycode auth` or configured your credentials before starting the MCP server.
 
@@ -649,6 +682,8 @@ This information can be helpful when:
 - Identifying authentication problems
 - Debugging transport-specific issues
 
+### MCP Configuration
+
 
 # Platform Command \[BETA\]
 

{cycode-3.15.3.dev7 → cycode-3.15.4.dev1}/README.md

@@ -21,6 +21,7 @@ This guide walks you through both installation and usage.
     2. [Available Options](#available-options)
     3. [MCP Tools](#mcp-tools)
     4. [Usage Examples](#usage-examples)
+    5. [Advanced Configuration](#advanced-configuration)
 5. [Platform Command](#platform-command-beta)
     1. [Discovering Commands](#discovering-commands)
     2. [Examples](#platform-examples)
@@ -559,6 +560,38 @@ cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &
 }
 ```
 
+### Advanced Configuration 
+##### Custom Certificates and Timeouts (Proxy Environments)
+
+If your organization uses a corporate proxy or a custom CA bundle for HTTPS inspection, you need to tell Cycode CLI (and the underlying Python TLS stack) where to find the trusted certificate bundle. You can also increase the MCP tool call timeout if scans are being cut short.
+
+| Environment Variable | Description |
+|----------------------|-------------|
+| `REQUESTS_CA_BUNDLE` | Path to a custom CA bundle file (`.pem` or `.crt`). Used by the `requests` library for all HTTPS calls made by Cycode CLI. |
+| `SSL_CERT_FILE`      | Path to a custom CA bundle file. Used by Python's low-level `ssl` module. Set this alongside `REQUESTS_CA_BUNDLE` for full coverage. |
+| `MCP_TOOL_TIMEOUT`   | Timeout (in seconds) that MCP clients such as Claude and GitHub Copilot wait for a tool call to complete. Increase this if long-running scans are being cut off before they finish. |
+
+> [!TIP]
+> Set both `REQUESTS_CA_BUNDLE` and `SSL_CERT_FILE` to the same CA bundle path. `REQUESTS_CA_BUNDLE` covers the HTTP layer; `SSL_CERT_FILE` covers the lower-level TLS layer. Using only one may still cause certificate errors in some environments.
+
+Example `mcp.json` configuration with custom certificates and a longer timeout:
+
+```json
+{
+  "mcpServers": {
+    "cycode": {
+      "command": "cycode",
+      "args": ["mcp"],
+      "env": {
+        "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
+        "SSL_CERT_FILE": "/path/to/your/corporate-ca-bundle.pem",
+        "MCP_TOOL_TIMEOUT": "1800"
+      }
+    }
+  }
+}
+```
+
 > [!NOTE]
 > The MCP server requires proper Cycode CLI authentication to function. Make sure you have authenticated using `cycode auth` or configured your credentials before starting the MCP server.
 
@@ -608,6 +641,8 @@ This information can be helpful when:
 - Identifying authentication problems
 - Debugging transport-specific issues
 
+### MCP Configuration
+
 
 # Platform Command \[BETA\]
 

cycode-3.15.4.dev1/cycode/__init__.py

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

cycode-3.15.4.dev1/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.dev1/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.3.dev7 → cycode-3.15.4.dev1}/cycode/cli/apps/ai_guardrails/hooks_manager.py

@@ -1,8 +1,8 @@
-"""
-Hooks manager for AI guardrails.
+"""Hooks manager for AI guardrails.
 
-Handles installation, removal, and status checking of AI IDE hooks.
-Supports multiple IDEs: Cursor, Claude Code (future).
+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
@@ -12,47 +12,45 @@ from typing import Optional
 
 import yaml
 
-from cycode.cli.apps.ai_guardrails.consts import (
-    DEFAULT_IDE,
-    IDE_CONFIGS,
-    AIIDEType,
-    PolicyMode,
-    get_hooks_config,
-)
+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')
 
 
-def get_hooks_path(scope: str, repo_path: Optional[Path] = None, ide: AIIDEType = DEFAULT_IDE) -> Path:
-    """Get the hooks.json path for the given scope and IDE.
+_CYCODE_COMMAND_MARKERS = ('cycode ai-guardrails',)
+
 
-    Args:
-        scope: 'user' for user-level hooks, 'repo' for repository-level hooks
-        repo_path: Repository path (required if scope is 'repo')
-        ide: The AI IDE type (default: Cursor)
-    """
-    config = IDE_CONFIGS[ide]
-    if scope == 'repo' and repo_path:
-        return repo_path / config.repo_hooks_subdir / config.hooks_file_name
-    return config.hooks_dir / config.hooks_file_name
+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:
+    """Detect Cycode hook entries in both Cursor (flat) and Claude Code (nested) shapes."""
+    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 load_hooks_file(hooks_path: Path) -> Optional[dict]:
-    """Load existing hooks.json file."""
+def _load_hooks_file(hooks_path: Path) -> Optional[dict]:
     if not hooks_path.exists():
         return None
     try:
-        content = hooks_path.read_text(encoding='utf-8')
-        return json.loads(content)
+        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:
-    """Save hooks.json file."""
+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')
@@ -62,39 +60,7 @@ def save_hooks_file(hooks_path: Path, hooks_config: dict) -> bool:
         return False
 
 
-_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:
-    """Check if a hook entry is from cycode-cli.
-
-    Handles both Cursor format (flat) and Claude Code format (nested).
-
-    Cursor format: {"command": "cycode ai-guardrails scan"}
-    Claude Code format: {"hooks": [{"type": "command", "command": "cycode ai-guardrails scan --ide claude-code"}]}
-    """
-    # Check Cursor format (flat command)
-    command = entry.get('command', '')
-    if _is_cycode_command(command):
-        return True
-
-    # Check Claude Code format (nested hooks array)
-    hooks = entry.get('hooks', [])
-    for hook in hooks:
-        if isinstance(hook, dict):
-            hook_command = hook.get('command', '')
-            if _is_cycode_command(hook_command):
-                return True
-
-    return False
-
-
-def _load_policy(policy_path: Path) -> dict:
-    """Load existing policy file merged with defaults, or return defaults if not found."""
+def _load_policy_dict(policy_path: Path) -> dict:
     if not policy_path.exists():
         return copy.deepcopy(DEFAULT_POLICY)
     try:
@@ -107,22 +73,13 @@ def _load_policy(policy_path: Path) -> dict:
 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.
-    If it doesn't exist, a new file is created from the default policy.
-
-    Args:
-        scope: 'user' for user-level, 'repo' for repository-level
-        mode: The policy mode to set
-        repo_path: Repository path (required if scope is 'repo')
-
-    Returns:
-        Tuple of (success, message)
+    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(policy_path)
-
+    policy = _load_policy_dict(policy_path)
     policy['mode'] = mode.value
 
     try:
@@ -135,35 +92,21 @@ def create_policy_file(scope: str, mode: PolicyMode, repo_path: Optional[Path] =
 
 
 def install_hooks(
+    ide: IDE,
     scope: str = 'user',
     repo_path: Optional[Path] = None,
-    ide: AIIDEType = DEFAULT_IDE,
     report_mode: bool = False,
 ) -> tuple[bool, str]:
-    """
-    Install Cycode AI guardrails hooks.
-
-    Args:
-        scope: 'user' for user-level hooks, 'repo' for repository-level hooks
-        repo_path: Repository path (required if scope is 'repo')
-        ide: The AI IDE type (default: Cursor)
-        report_mode: If True, install hooks in async mode (non-blocking)
+    """Install Cycode AI guardrails hooks for ``ide``."""
+    hooks_path = ide.settings_path(scope, repo_path)
 
-    Returns:
-        Tuple of (success, message)
-    """
-    hooks_path = get_hooks_path(scope, repo_path, ide)
-
-    # Load existing hooks or create new
-    existing = load_hooks_file(hooks_path) or {'version': 1, 'hooks': {}}
+    existing = _load_hooks_file(hooks_path) or {'version': 1, 'hooks': {}}
     existing.setdefault('version', 1)
     existing.setdefault('hooks', {})
 
-    # Get IDE-specific hooks configuration
-    hooks_config = get_hooks_config(ide, async_mode=report_mode)
+    rendered = ide.render_hooks_config(async_mode=report_mode)
 
-    # Add/update Cycode hooks
-    for event, entries in hooks_config['hooks'].items():
+    for event, entries in rendered['hooks'].items():
         existing['hooks'].setdefault(event, [])
 
         # Remove any existing Cycode entries for this event
@@ -173,47 +116,31 @@ def install_hooks(
         for entry in entries:
             existing['hooks'][event].append(entry)
 
-    # Save
-    if save_hooks_file(hooks_path, existing):
+    if _save_hooks_file(hooks_path, existing):
         return True, f'AI guardrails hooks installed: {hooks_path}'
     return False, f'Failed to install hooks to {hooks_path}'
 
 
-def uninstall_hooks(
-    scope: str = 'user', repo_path: Optional[Path] = None, ide: AIIDEType = DEFAULT_IDE
-) -> tuple[bool, str]:
-    """
-    Remove Cycode AI guardrails hooks.
-
-    Args:
-        scope: 'user' for user-level hooks, 'repo' for repository-level hooks
-        repo_path: Repository path (required if scope is 'repo')
-        ide: The AI IDE type (default: Cursor)
-
-    Returns:
-        Tuple of (success, message)
-    """
-    hooks_path = get_hooks_path(scope, repo_path, ide)
+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)
+    existing = _load_hooks_file(hooks_path)
     if existing is None:
         return True, f'No hooks file found at {hooks_path}'
 
-    # Remove Cycode entries from all events
     modified = False
     for event in list(existing.get('hooks', {}).keys()):
         original_count = len(existing['hooks'][event])
         existing['hooks'][event] = [e for e in existing['hooks'][event] if not is_cycode_hook_entry(e)]
         if len(existing['hooks'][event]) != original_count:
             modified = True
-        # Remove empty event lists
         if not existing['hooks'][event]:
             del existing['hooks'][event]
 
     if not modified:
         return True, 'No Cycode hooks found to remove'
 
-    # Save or delete if empty
     if not existing.get('hooks'):
         try:
             hooks_path.unlink()
@@ -222,48 +149,35 @@ def uninstall_hooks(
             logger.debug('Failed to delete hooks file', exc_info=e)
             return False, f'Failed to remove hooks file: {hooks_path}'
 
-    if save_hooks_file(hooks_path, existing):
+    if _save_hooks_file(hooks_path, existing):
         return True, f'Cycode hooks removed from: {hooks_path}'
     return False, f'Failed to update hooks file: {hooks_path}'
 
 
-def get_hooks_status(scope: str = 'user', repo_path: Optional[Path] = None, ide: AIIDEType = DEFAULT_IDE) -> dict:
-    """
-    Get the status of AI guardrails hooks.
-
-    Args:
-        scope: 'user' for user-level hooks, 'repo' for repository-level hooks
-        repo_path: Repository path (required if scope is 'repo')
-        ide: The AI IDE type (default: Cursor)
-
-    Returns:
-        Dict with status information
-    """
-    hooks_path = get_hooks_path(scope, repo_path, ide)
+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 = {
+    status: dict = {
         'scope': scope,
-        'ide': ide.value,
-        'ide_name': IDE_CONFIGS[ide].name,
+        '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)
+    existing = _load_hooks_file(hooks_path)
     if existing is None:
         return status
 
-    # Check each hook event for this IDE
-    ide_config = IDE_CONFIGS[ide]
     has_cycode_hooks = False
-    for event in ide_config.hook_events:
-        # Handle event:matcher format
+    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, [])
-            # Filter entries by matcher
             entries = [e for e in all_entries if e.get('matcher', '').startswith(matcher_prefix)]
         else:
             entries = existing.get('hooks', {}).get(event, [])
@@ -278,5 +192,4 @@ def get_hooks_status(scope: str = 'user', repo_path: Optional[Path] = None, ide:
         }
 
     status['cycode_installed'] = has_cycode_hooks
-
     return status

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

@@ -0,0 +1,44 @@
+"""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.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())}
+
+# 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)]