cycode 3.23.0__tar.gz → 3.23.1.dev1__tar.gz

{cycode-3.23.0 → cycode-3.23.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cycode
-Version: 3.23.0
+Version: 3.23.1.dev1
 Summary: Boost security in your dev lifecycle via SAST, SCA, Secrets & IaC scanning.
 License-Expression: MIT
 License-File: LICENCE

{cycode-3.23.0 → cycode-3.23.1.dev1}/cycode/__init__.py

@@ -5,4 +5,4 @@ import time as _time
 # end-to-end scan duration from the moment the user actually triggered it.
 _BOOT_WALL: float = _time.time()
 
-__version__ = '3.23.0'  # DON'T TOUCH. Placeholder. Will be filled automatically on poetry build from Git Tag
+__version__ = '3.23.1.dev1'  # DON'T TOUCH. Placeholder. Will be filled automatically on poetry build from Git Tag

{cycode-3.23.0 → cycode-3.23.1.dev1}/cycode/cli/apps/ai_guardrails/consts.py

@@ -22,6 +22,18 @@ class GuardrailsMode(str, Enum):
     BLOCK = 'block'
 
 
+class GuardrailCellMode(str, Enum):
+    """A guardrail x agent cell in the platform-resolved matrix.
+
+    Separate from GuardrailsMode because Off is a platform-only state: it is not an
+    install `--mode` choice, and an off guardrail reports no mode to the server.
+    """
+
+    OFF = 'off'
+    REPORT = GuardrailsMode.REPORT.value
+    BLOCK = GuardrailsMode.BLOCK.value
+
+
 # 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-3.23.0 → cycode-3.23.1.dev1}/cycode/cli/apps/ai_guardrails/hooks_manager.py

@@ -12,9 +12,9 @@ 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.cli.apps.ai_guardrails.scan.policy import strip_platform_managed_keys
 from cycode.logger import get_logger
 
 logger = get_logger('AI Guardrails Hooks')
@@ -102,22 +102,21 @@ def _load_policy_dict(policy_path: Path) -> dict:
     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.
+def create_policy_file(scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+    """Create or update the ai-guardrails.yaml policy file (operational knobs only).
 
-    If the file already exists, only the mode field is updated; otherwise a new
-    file is created from the default policy.
+    Enforcement mode and sensitive-path globs are platform-managed; those keys are stripped
+    (including ones an older CLI wrote), everything else the user customized is preserved.
     """
     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
+    policy = strip_platform_managed_keys(_load_policy_dict(policy_path))
 
     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}'
+        return True, f'AI guardrails policy file 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}'

{cycode-3.23.0 → cycode-3.23.1.dev1}/cycode/cli/apps/ai_guardrails/install_command.py

@@ -6,7 +6,7 @@ from typing import Annotated, Optional
 import typer
 
 from cycode.cli.apps.ai_guardrails.command_utils import console, resolve_repo_path, validate_scope
-from cycode.cli.apps.ai_guardrails.consts import GuardrailsMode, PolicyMode
+from cycode.cli.apps.ai_guardrails.consts import GuardrailsMode
 from cycode.cli.apps.ai_guardrails.hooks_manager import create_policy_file, install_hooks
 from cycode.cli.apps.ai_guardrails.ides import DEFAULT_IDE_NAME, IDES, resolve_ides
 
@@ -44,8 +44,7 @@ def install_command(
         typer.Option(
             '--mode',
             '-m',
-            help='Installation mode: "report" for async non-blocking hooks with warn policy, '
-            '"block" for sync blocking hooks.',
+            help='[Deprecated] Enforcement mode is platform-managed; configure guardrails in the Cycode platform.',
         ),
     ] = GuardrailsMode.REPORT,
 ) -> None:
@@ -80,32 +79,34 @@ def install_command(
             console.print(f'[red]✗[/] {message}', style='bold red')
             all_success = False
 
+    if mode == GuardrailsMode.BLOCK:
+        console.print(
+            '[yellow]--mode is deprecated:[/] enforcement mode is platform-managed; '
+            'configure guardrails in the Cycode platform.'
+        )
+
     if any_success:
-        policy_mode = PolicyMode.WARN if mode == GuardrailsMode.REPORT else PolicyMode.BLOCK
-        _install_policy(scope, repo_path, policy_mode)
-        _print_next_steps(results, mode)
+        _install_policy(scope, repo_path)
+        _print_next_steps(results)
 
     if not all_success:
         raise typer.Exit(1)
 
 
-def _install_policy(scope: str, repo_path: Optional[Path], policy_mode: PolicyMode) -> None:
-    policy_success, policy_message = create_policy_file(scope, policy_mode, repo_path)
+def _install_policy(scope: str, repo_path: Optional[Path]) -> None:
+    policy_success, policy_message = create_policy_file(scope, repo_path)
     if policy_success:
         console.print(f'[green]✓[/] {policy_message}')
     else:
         console.print(f'[red]✗[/] {policy_message}', style='bold red')
 
 
-def _print_next_steps(results: list[tuple[str, bool, str]], mode: GuardrailsMode) -> None:
+def _print_next_steps(results: list[tuple[str, bool, str]]) -> None:
     console.print()
     console.print('[bold]Next steps:[/]')
     successful_ides = [name for name, success, _ in results if success]
     ide_list = ', '.join(successful_ides)
     console.print(f'1. Restart {ide_list} to activate the hooks')
-    console.print('2. (Optional) Customize policy in ~/.cycode/ai-guardrails.yaml')
+    console.print('2. Configure guardrail enforcement in the Cycode platform')
     console.print()
-    if mode == GuardrailsMode.REPORT:
-        console.print('[dim]Report mode: policy is set to warn.[/]')
-    else:
-        console.print('[dim]The hooks will scan prompts, file reads, and MCP tool calls for secrets.[/]')
+    console.print('[dim]The hooks will scan prompts, file reads, and MCP tool calls for secrets.[/]')

cycode-3.23.1.dev1/cycode/cli/apps/ai_guardrails/scan/consts.py

@@ -0,0 +1,37 @@
+"""
+Constants and default configuration for AI guardrails.
+
+Enforcement (which guardrails run, in which mode, over which paths) is platform-owned and
+resolved per scan; see scan/guardrail_config.py. What is left here is the operational knobs
+a local file may override - user-level ~/.cycode/ai-guardrails.yaml, then repo-level
+<workspace>/.cycode/ai-guardrails.yaml.
+"""
+
+# Policy file name
+POLICY_FILE_NAME = 'ai-guardrails.yaml'
+
+# Sensitive-path globs used until the platform's own list is cached (cold start, or a tenant
+# that never customized them). Not a local knob: apply_platform_config always overwrites it.
+DEFAULT_SENSITIVE_PATH_GLOBS = [
+    '.env',
+    '.env.*',
+    '*.pem',
+    '*.p12',
+    '*.key',
+    '.aws/**',
+    '.ssh/**',
+    '*kubeconfig*',
+    '.npmrc',
+    '.netrc',
+]
+
+# Default policy configuration: operational knobs only.
+DEFAULT_POLICY = {
+    'version': 1,
+    'fail_open': True,  # allow if scan fails/timeouts
+    'secrets': {
+        'scan_type': 'secret',
+        'timeout_ms': 30000,
+        'max_bytes': 200000,
+    },
+}

cycode-3.23.1.dev1/cycode/cli/apps/ai_guardrails/scan/guardrail_config.py

@@ -0,0 +1,165 @@
+"""Platform guardrail config cache.
+
+session-start fetches the tenant's resolved guardrail config from the platform and writes it
+here; scans only read. Per-agent modes and sensitive-path globs are platform-owned - local
+policy files never carry them. An absent or corrupt cache means built-in defaults (Report
+everywhere + the default globs), always synchronous.
+"""
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from cycode.cli.apps.ai_guardrails.consts import GuardrailCellMode, PolicyMode
+from cycode.cli.apps.ai_guardrails.scan.consts import DEFAULT_SENSITIVE_PATH_GLOBS
+from cycode.cli.apps.ai_guardrails.scan.types import BlockReason
+from cycode.cli.consts import CYCODE_CONFIGURATION_DIRECTORY
+from cycode.cli.utils.path_utils import atomic_write_text, quarantine_corrupt_file
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails')
+
+GUARDRAILS_CONFIG_FILE_NAME = 'ai-guardrails-config.json'
+
+_DEFAULT_TTL_SECONDS = 900
+
+# Guardrail keys are the CLI's block-reason vocabulary. Anything else in the payload (a future
+# guardrail this CLI doesn't implement) is ignored - unknown config must never fail closed.
+_KNOWN_GUARDRAIL_KEYS = frozenset(
+    reason.value
+    for reason in (
+        BlockReason.SECRETS_IN_PROMPT,
+        BlockReason.SECRETS_IN_FILE,
+        BlockReason.SENSITIVE_PATH,
+        BlockReason.SECRETS_IN_MCP_ARGS,
+    )
+)
+
+# CLI --ide names to matrix column names; identity for names not listed.
+_AGENT_BY_IDE_NAME = {'claude-code': 'claude'}
+
+
+def get_config_cache_path() -> Path:
+    return Path.home() / CYCODE_CONFIGURATION_DIRECTORY / GUARDRAILS_CONFIG_FILE_NAME
+
+
+def agent_for_ide(ide_name: Optional[str]) -> str:
+    ide_name = (ide_name or '').lower()
+    return _AGENT_BY_IDE_NAME.get(ide_name, ide_name)
+
+
+def _default_sensitive_globs() -> list:
+    return list(DEFAULT_SENSITIVE_PATH_GLOBS)
+
+
+@dataclass
+class GuardrailConfig:
+    payload: dict
+    fetched_at: float
+    tenant_id: Optional[str] = None
+    _guardrails: dict = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._guardrails = {
+            guardrail.get('key'): guardrail
+            for guardrail in self.payload.get('guardrails') or []
+            if guardrail.get('key') in _KNOWN_GUARDRAIL_KEYS
+        }
+
+    def mode_for(self, guardrail_key: str, ide_name: Optional[str]) -> str:
+        agents = (self._guardrails.get(guardrail_key) or {}).get('agents') or {}
+        return str(agents.get(agent_for_ide(ide_name), GuardrailCellMode.REPORT.value)).lower()
+
+    def _modes_for_event(self, event_name: str, ide_name: Optional[str]) -> list:
+        return [
+            self.mode_for(key, ide_name)
+            for key, guardrail in self._guardrails.items()
+            if str(guardrail.get('event_type', '')).lower() == str(event_name).lower()
+        ]
+
+    def is_event_off(self, event_name: str, ide_name: Optional[str]) -> bool:
+        """Every guardrail for this event is Off - skip the scan entirely."""
+        modes = self._modes_for_event(event_name, ide_name)
+        return bool(modes) and all(mode == GuardrailCellMode.OFF for mode in modes)
+
+    def can_event_block(self, event_name: str, ide_name: Optional[str]) -> bool:
+        """At least one guardrail for this event is in Block mode - the scan must stay synchronous."""
+        return GuardrailCellMode.BLOCK in self._modes_for_event(event_name, ide_name)
+
+    def sensitive_globs(self) -> list:
+        settings = (self._guardrails.get(BlockReason.SENSITIVE_PATH) or {}).get('settings') or {}
+        globs = settings.get('globs')
+        return globs if isinstance(globs, list) and globs else _default_sensitive_globs()
+
+    def is_expired(self) -> bool:
+        ttl = self.payload.get('ttl_seconds') or _DEFAULT_TTL_SECONDS
+        return time.time() - self.fetched_at > ttl
+
+    def needs_refresh(self, tenant_id: Optional[str]) -> bool:
+        """Expired, or fetched for another tenant (the user switched tenants since)."""
+        return self.is_expired() or self.tenant_id != tenant_id
+
+
+def apply_platform_config(policy: dict, config: Optional[GuardrailConfig], ide_name: Optional[str]) -> None:
+    """Overlay the platform-owned enforcement config onto the local knobs-only policy.
+
+    The platform is the only mode source: no cache (cold start) means the built-in defaults -
+    Report everywhere with the default globs - which equal an unconfigured tenant's platform
+    config, so behaviour is uniform either way. Each matrix cell lands on its own per-feature
+    action, so the two FileRead guardrails (content scan vs. sensitive path) keep independent modes.
+    An all-Off event never reaches here at all: scan_command skips it.
+    """
+
+    def cell(guardrail_key: str) -> str:
+        return config.mode_for(guardrail_key, ide_name) if config is not None else GuardrailCellMode.REPORT.value
+
+    def action(guardrail_key: str) -> str:
+        return PolicyMode.BLOCK.value if cell(guardrail_key) == GuardrailCellMode.BLOCK else PolicyMode.WARN.value
+
+    policy.setdefault('prompt', {})['action'] = action(BlockReason.SECRETS_IN_PROMPT)
+
+    file_read = policy.setdefault('file_read', {})
+    file_read['scan_content'] = cell(BlockReason.SECRETS_IN_FILE) != GuardrailCellMode.OFF
+    file_read['action'] = action(BlockReason.SECRETS_IN_FILE)
+    file_read['deny_globs'] = (
+        (config.sensitive_globs() if config is not None else _default_sensitive_globs())
+        if cell(BlockReason.SENSITIVE_PATH) != GuardrailCellMode.OFF
+        else []
+    )
+    file_read['path_action'] = action(BlockReason.SENSITIVE_PATH)
+
+    policy.setdefault('mcp', {})['action'] = action(BlockReason.SECRETS_IN_MCP_ARGS)
+
+
+def save_guardrail_config(payload: dict, tenant_id: Optional[str]) -> None:
+    """Persist a fetched resolved config; a failed write just leaves the previous cache in place."""
+    path = get_config_cache_path()
+    content = {'fetched_at': time.time(), 'tenant_id': tenant_id, 'payload': payload}
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_text(str(path), json.dumps(content))
+    except Exception as e:
+        logger.debug('Failed to save guardrail config cache', exc_info=e)
+
+
+def load_guardrail_config() -> Optional[GuardrailConfig]:
+    """The cached platform config, or None when it is absent or corrupt (quarantined)."""
+    path = get_config_cache_path()
+    if not path.exists():
+        return None
+
+    try:
+        with open(path, encoding='UTF-8') as file:
+            content = json.load(file)
+        payload = content['payload']
+        if not isinstance(payload, dict):
+            raise ValueError('payload is not an object')
+        return GuardrailConfig(
+            payload=payload, fetched_at=float(content['fetched_at']), tenant_id=content.get('tenant_id')
+        )
+    except Exception as e:
+        logger.warning('Guardrail config cache is corrupt and will be moved aside', exc_info=e)
+        quarantine_corrupt_file(str(path))
+        return None

{cycode-3.23.0 → cycode-3.23.1.dev1}/cycode/cli/apps/ai_guardrails/scan/handlers.py

@@ -13,10 +13,13 @@ import os
 from dataclasses import dataclass
 from multiprocessing.pool import ThreadPool
 from multiprocessing.pool import TimeoutError as PoolTimeoutError
-from typing import Callable, Optional
+from typing import TYPE_CHECKING, Callable, Optional
 
 import typer
 
+if TYPE_CHECKING:
+    from cycode.cli.apps.ai_guardrails.scan.guardrail_config import GuardrailConfig
+
 from cycode.cli.apps.ai_guardrails.consts import GuardrailsMode, PolicyMode
 from cycode.cli.apps.ai_guardrails.ides.base import HookDecision
 from cycode.cli.apps.ai_guardrails.scan.payload import AIHookPayload
@@ -48,11 +51,7 @@ def handle_before_submit_prompt(ctx: typer.Context, payload: AIHookPayload, poli
     ai_client = ctx.obj['ai_security_client']
 
     prompt_config = get_policy_value(policy, 'prompt', default={})
-    if not get_policy_value(prompt_config, 'enabled', default=True):
-        ai_client.create_event(payload, AiHookEventType.PROMPT, AIHookOutcome.ALLOWED)
-        return HookDecision.allow(AiHookEventType.PROMPT)
-
-    effective_mode = get_effective_mode(policy, prompt_config)
+    effective_mode = get_effective_mode(prompt_config)
     prompt = payload.prompt or ''
     max_bytes = get_policy_value(policy, 'secrets', 'max_bytes', default=200000)
     timeout_ms = get_policy_value(policy, 'secrets', 'timeout_ms', default=30000)
@@ -104,12 +103,9 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
     ai_client = ctx.obj['ai_security_client']
 
     file_read_config = get_policy_value(policy, 'file_read', default={})
-    if not get_policy_value(file_read_config, 'enabled', default=True):
-        ai_client.create_event(payload, AiHookEventType.FILE_READ, AIHookOutcome.ALLOWED)
-        return HookDecision.allow(AiHookEventType.FILE_READ)
-
     file_path = payload.file_path or ''
-    effective_mode = get_effective_mode(policy, file_read_config)
+    path_mode = get_effective_mode(file_read_config, action_key='path_action')
+    content_mode = get_effective_mode(file_read_config)
 
     scan_id = None
     block_reason = None
@@ -120,7 +116,7 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
         is_sensitive_path = is_denied_path(file_path, policy)
         if is_sensitive_path:
             block_reason = BlockReason.SENSITIVE_PATH
-            if effective_mode == GuardrailsMode.BLOCK:
+            if path_mode == GuardrailsMode.BLOCK:
                 outcome = AIHookOutcome.BLOCKED
                 user_message = f'Cycode blocked sending {file_path} to the AI (sensitive path policy).'
                 return HookDecision.deny(
@@ -144,11 +140,11 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
 
         if get_policy_value(file_read_config, 'scan_content', default=True):
             violation_summary, scan_id = _scan_path_for_secrets(
-                ctx, file_path, policy, payload=payload, effective_mode=effective_mode
+                ctx, file_path, policy, payload=payload, effective_mode=content_mode
             )
             if violation_summary:
                 block_reason = SECRETS_BLOCK_REASON_BY_EVENT_TYPE[AiHookEventType.FILE_READ]
-                if effective_mode == GuardrailsMode.BLOCK:
+                if content_mode == GuardrailsMode.BLOCK:
                     outcome = AIHookOutcome.BLOCKED
                     user_message = f'Cycode blocked reading {file_path}. {violation_summary}'
                     return HookDecision.deny(
@@ -201,7 +197,6 @@ class _ArgScanFeature:
     """
 
     policy_key: str  # 'mcp' or 'command_exec'
-    scan_key: str  # 'scan_arguments' or 'scan_command'
     event_type: AiHookEventType
     deny_message: Callable[[str], str]
     deny_agent_message: str
@@ -220,14 +215,10 @@ def _handle_arg_scan(
     ai_client = ctx.obj['ai_security_client']
 
     feature_config = get_policy_value(policy, feature.policy_key, default={})
-    if not get_policy_value(feature_config, 'enabled', default=True):
-        ai_client.create_event(payload, feature.event_type, AIHookOutcome.ALLOWED)
-        return HookDecision.allow(feature.event_type)
-
     max_bytes = get_policy_value(policy, 'secrets', 'max_bytes', default=200000)
     timeout_ms = get_policy_value(policy, 'secrets', 'timeout_ms', default=30000)
     clipped = truncate_utf8(scan_text, max_bytes)
-    effective_mode = get_effective_mode(policy, feature_config)
+    effective_mode = get_effective_mode(feature_config)
 
     scan_id = None
     block_reason = None
@@ -235,30 +226,29 @@ def _handle_arg_scan(
     error_message = None
 
     try:
-        if get_policy_value(feature_config, feature.scan_key, default=True):
-            violation_summary, scan_id = _scan_text_for_secrets(
-                ctx,
-                clipped,
-                timeout_ms,
-                payload=payload,
-                event_type=feature.event_type,
-                effective_mode=effective_mode,
-            )
-            if violation_summary:
-                block_reason = SECRETS_BLOCK_REASON_BY_EVENT_TYPE[feature.event_type]
-                if effective_mode == GuardrailsMode.BLOCK:
-                    outcome = AIHookOutcome.BLOCKED
-                    return HookDecision.deny(
-                        feature.event_type,
-                        feature.deny_message(violation_summary),
-                        feature.deny_agent_message,
-                    )
-                outcome = AIHookOutcome.WARNED
-                return HookDecision.ask(
+        violation_summary, scan_id = _scan_text_for_secrets(
+            ctx,
+            clipped,
+            timeout_ms,
+            payload=payload,
+            event_type=feature.event_type,
+            effective_mode=effective_mode,
+        )
+        if violation_summary:
+            block_reason = SECRETS_BLOCK_REASON_BY_EVENT_TYPE[feature.event_type]
+            if effective_mode == GuardrailsMode.BLOCK:
+                outcome = AIHookOutcome.BLOCKED
+                return HookDecision.deny(
                     feature.event_type,
-                    feature.ask_message(violation_summary),
-                    feature.ask_agent_message,
+                    feature.deny_message(violation_summary),
+                    feature.deny_agent_message,
                 )
+            outcome = AIHookOutcome.WARNED
+            return HookDecision.ask(
+                feature.event_type,
+                feature.ask_message(violation_summary),
+                feature.ask_agent_message,
+            )
 
         return HookDecision.allow(feature.event_type)
     except Exception as e:
@@ -290,7 +280,6 @@ def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, poli
         policy,
         _ArgScanFeature(
             policy_key='mcp',
-            scan_key='scan_arguments',
             event_type=AiHookEventType.MCP_EXECUTION,
             deny_message=lambda v: f'Cycode blocked MCP tool call "{tool}". {v}',
             deny_agent_message='Do not pass secrets to tools. Use secret references (name/id) instead.',
@@ -311,35 +300,29 @@ def get_handler_for_event(event_type: str) -> Optional[HandlerFn]:
     return handlers.get(event_type)
 
 
-def get_effective_mode(policy: dict, feature_config: dict) -> GuardrailsMode:
-    """The event only blocks when both the global mode and the per-guardrail action are block."""
-    mode = get_policy_value(policy, 'mode', default=PolicyMode.BLOCK)
-    action = get_policy_value(feature_config, 'action', default=PolicyMode.BLOCK)
-    return GuardrailsMode.BLOCK if (mode == PolicyMode.BLOCK and action == PolicyMode.BLOCK) else GuardrailsMode.REPORT
-
+def get_effective_mode(feature_config: dict, action_key: str = 'action') -> GuardrailsMode:
+    """A guardrail's action is its matrix cell: block, or warn (report) for everything else."""
+    action = get_policy_value(feature_config, action_key, default=PolicyMode.BLOCK)
+    return GuardrailsMode.BLOCK if action == PolicyMode.BLOCK else GuardrailsMode.REPORT
 
-# The policy section each event's handler reads its feature config from.
-_FEATURE_KEY_BY_EVENT_TYPE: dict[str, str] = {
-    AiHookEventType.PROMPT.value: 'prompt',
-    AiHookEventType.FILE_READ.value: 'file_read',
-    AiHookEventType.MCP_EXECUTION.value: 'mcp',
-}
 
-
-def should_detach_scan(policy: dict, event_name: str) -> bool:
+def should_detach_scan(
+    config: Optional['GuardrailConfig'],
+    policy: dict,
+    event_name: str,
+    ide_name: Optional[str],
+) -> bool:
     """Whether this event's scan is safe to run detached.
 
-    Report mode never blocks, so nobody consumes the verdict. Fail-closed
-    configs stay synchronous even in report mode: their deny on scan failure
-    must reach the IDE. Unknown events stay synchronous - they exit fast anyway.
+    Report mode never blocks, so nobody consumes the verdict. The platform config is the only
+    mode source: without a cache the scan stays synchronous (never detach on an assumption).
+    Fail-closed configs also stay synchronous: their deny on scan failure must reach the IDE.
     """
-    feature_key = _FEATURE_KEY_BY_EVENT_TYPE.get(event_name)
-    if feature_key is None:
+    if config is None:
         return False
     if not get_policy_value(policy, 'fail_open', default=True):
         return False
-    feature_config = get_policy_value(policy, feature_key, default={})
-    return get_effective_mode(policy, feature_config) == GuardrailsMode.REPORT
+    return not config.can_event_block(event_name, ide_name)
 
 
 def build_ai_guardrails_scan_parameters(

{cycode-3.23.0 → cycode-3.23.1.dev1}/cycode/cli/apps/ai_guardrails/scan/policy.py

@@ -1,11 +1,14 @@
 """
 Policy loading and configuration management for AI guardrails.
 
-Policies are loaded and merged in order (later overrides earlier):
+Operational knobs are loaded and merged in order (later overrides earlier):
 1. Built-in defaults (consts.DEFAULT_POLICY)
 2. Machine-wide config (admin/MDM-provisioned; see get_machine_policy_path)
 3. User-level config (~/.cycode/ai-guardrails.yaml)
 4. Repo-level config (<workspace>/.cycode/ai-guardrails.yaml)
+
+Enforcement is not part of that merge: the platform resolves it and apply_platform_config
+overlays it on top of the result (see scan/guardrail_config.py).
 """
 
 import json
@@ -17,6 +20,34 @@ from typing import Any, Optional
 import yaml
 
 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')
+
+# A local policy file may only contribute operational knobs; enforcement comes from the
+# platform. Read as a whitelist rather than a strip-list, so a key we forget to enumerate
+# is ignored by default instead of silently weakening enforcement.
+_LOCAL_POLICY_KEYS = ('version', 'fail_open', 'secrets')
+
+# The sections the platform resolves. Only used when rewriting a user's file: keys an older
+# CLI wrote there still read as enforcement to a human, so drop them on the way out.
+_PLATFORM_OWNED_KEYS = ('mode', 'prompt', 'file_read', 'mcp')
+
+
+def pick_local_knobs(config: dict, filename: str) -> dict:
+    """Keep only the keys a local policy file is allowed to contribute."""
+    ignored = [key for key in config if key not in _LOCAL_POLICY_KEYS]
+    if ignored:
+        logger.debug(
+            'Ignoring non-knob keys in local policy file, %s',
+            {'filename': filename, 'keys': ignored},
+        )
+    return {key: value for key, value in config.items() if key in _LOCAL_POLICY_KEYS}
+
+
+def strip_platform_managed_keys(config: dict) -> dict:
+    """Drop the enforcement sections a local file may carry (older CLIs wrote them)."""
+    return {key: value for key, value in config.items() if key not in _PLATFORM_OWNED_KEYS}
 
 
 def get_machine_policy_path() -> Path:
@@ -83,21 +114,22 @@ def load_policy(workspace_root: Optional[str] = None) -> dict:
     policy = load_defaults()
 
     # Merge machine-wide config (admin/MDM-provisioned) - overrides defaults, below user/repo.
-    machine_config = load_yaml_file(get_machine_policy_path())
+    machine_policy_path = get_machine_policy_path()
+    machine_config = load_yaml_file(machine_policy_path)
     if machine_config:
-        policy = deep_merge(policy, machine_config)
+        policy = deep_merge(policy, pick_local_knobs(machine_config, str(machine_policy_path)))
 
     # Merge user-level config (if exists)
     user_policy_path = Path.home() / '.cycode' / POLICY_FILE_NAME
     user_config = load_yaml_file(user_policy_path)
     if user_config:
-        policy = deep_merge(policy, user_config)
+        policy = deep_merge(policy, pick_local_knobs(user_config, str(user_policy_path)))
 
     # Merge repo-level config (if exists) - highest precedence
     if workspace_root:
         repo_policy_path = Path(workspace_root) / '.cycode' / POLICY_FILE_NAME
         repo_config = load_yaml_file(repo_policy_path)
         if repo_config:
-            policy = deep_merge(policy, repo_config)
+            policy = deep_merge(policy, pick_local_knobs(repo_config, str(repo_policy_path)))
 
     return policy