CM-68943 Send ai-guardrails hook context with the scan so report-mode findings become violations

README.md

@@ -28,7 +28,9 @@ This guide walks you through both installation and usage.
  1. [Discovering Commands](#discovering-commands)
  2. [Examples](#platform-examples)
  3. [Notes & Limitations](#platform-notes--limitations)
-6. [Scan Command](#scan-command)
+6. [AI Guardrails](#ai-guardrails-beta)
+ 1. [Data Collected by AI Guardrails](#data-collected-by-ai-guardrails)
+7. [Scan Command](#scan-command)
  1. [Running a Scan](#running-a-scan)
  1. [Options](#options)
  1. [Severity Threshold](#severity-option)
@@ -704,6 +706,32 @@ cycode platform projects list --page-size 100 | jq '.items[].name'
 - **Override the cache TTL** with `CYCODE_SPEC_CACHE_TTL=<seconds>`.
 
 
+# AI Guardrails \[BETA\]
+
+AI Guardrails installs hooks into supported AI coding agents (Claude Code, Cursor, Copilot, Codex) so that
+prompts, files the agent reads, and MCP tool arguments are scanned for secrets before they reach the model.
+
+## Data Collected by AI Guardrails
+
+Scanning happens server-side, so the scanned content leaves the machine: the prompt text, the contents of
+files the agent reads, and MCP tool arguments are sent to your Cycode tenant to be checked for secrets.
+
+Each event is also reported with context about the developer and the machine, so a finding can be attributed
+to the device and user it came from. Some of this is personal data:
+
+- **Device identifiers** — the machine's hostname and hardware serial number.
+- **User identifiers** — the email address of the user signed in to the AI coding agent, and the local
+ operating-system username.
+- **Environment details** — operating system and version, the AI agent, its version and the model in use,
+ the contents of the agent's MCP configuration files, and its enabled plugins.
+
+The hardware serial number is cached in a local temporary file, readable only by the user who ran the
+command, so repeated hook invocations don't re-query the hardware.
+
+If collecting this data is not acceptable in your environment, do not install the guardrails hooks
+(`cycode ai-guardrails uninstall` removes hooks that are already installed).
+
+
 # Scan Command
 
 ## Running a Scan

cycode/cli/apps/ai_guardrails/consts.py

@@ -10,8 +10,13 @@ class PolicyMode(str, Enum):
  WARN = 'warn'
 
 
-class InstallMode(str, Enum):
- """Installation mode for ai-guardrails install command."""
+class GuardrailsMode(str, Enum):
+ """Guardrails enforcement mode.
+
+ Used both as the ai-guardrails install-command mode and as the per-event
+ effective mode reported to the server (the ai_guardrails scan parameter's
+ `mode` field)
+ """
 
  REPORT = 'report'
  BLOCK = 'block'

cycode/cli/apps/ai_guardrails/ides/copilot.py

@@ -333,9 +333,7 @@ def entry(command: str) -> dict:
  return {
  'version': 1,
  'hooks': {
- 'sessionStart': [
- {'type': 'command', 'command': _SESSION_START_COMMAND, 'timeoutSec': _HOOK_TIMEOUT_SEC}
- ],
+ 'sessionStart': [{'type': 'command', 'command': _SESSION_START_COMMAND}],
  'userPromptSubmitted': [entry(_SCAN_PROMPT_COMMAND)],
  'preToolUse': [entry(_SCAN_TOOL_COMMAND)],
  },

cycode/cli/apps/ai_guardrails/install_command.py

@@ -6,7 +6,7 @@
 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 InstallMode, PolicyMode
+from cycode.cli.apps.ai_guardrails.consts import GuardrailsMode, PolicyMode
 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
 
@@ -40,14 +40,14 @@ def install_command(
  ),
  ] = None,
  mode: Annotated[
-InstallMode,
+GuardrailsMode,
  typer.Option(
  '--mode',
  '-m',
  help='Installation mode: "report" for async non-blocking hooks with warn policy, '
  '"block" for sync blocking hooks.',
  ),
- ] = InstallMode.REPORT,
+ ] = GuardrailsMode.REPORT,
 ) -> None:
  """Install AI guardrails hooks for supported IDEs.
 
@@ -65,7 +65,7 @@ def install_command(
  repo_path = resolve_repo_path(scope, repo_path)
  ides_to_install = resolve_ides(ide)
 
- report_mode = mode == InstallMode.REPORT
+ report_mode = mode == GuardrailsMode.REPORT
 
  results: list[tuple[str, bool, str]] = []
  for current_ide in ides_to_install:
@@ -83,7 +83,7 @@ def install_command(
  all_success = False
 
  if any_success:
- policy_mode = PolicyMode.WARN if mode == InstallMode.REPORT else PolicyMode.BLOCK
+ policy_mode = PolicyMode.WARN if mode == GuardrailsMode.REPORT else PolicyMode.BLOCK
  _install_policy(scope, repo_path, policy_mode)
  _print_next_steps(results, mode)
 
@@ -99,15 +99,15 @@ def _install_policy(scope: str, repo_path: Optional[Path], policy_mode: PolicyMo
  console.print(f'[red]✗[/] {policy_message}', style='bold red')
 
 
-def _print_next_steps(results: list[tuple[str, bool, str]], mode: InstallMode) -> None:
+def _print_next_steps(results: list[tuple[str, bool, str]], mode: GuardrailsMode) -> 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()
- if mode == InstallMode.REPORT:
+ if mode == GuardrailsMode.REPORT:
  console.print('[dim]Report mode: hooks run async (non-blocking) and policy is set to warn.[/]')
  else:
  console.print('[dim]The hooks will scan prompts, file reads, and MCP tool calls for secrets.[/]')

cycode/cli/apps/ai_guardrails/scan/handlers.py

@@ -17,24 +17,29 @@
 
 import typer
 
-from cycode.cli.apps.ai_guardrails.consts import PolicyMode
+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
 from cycode.cli.apps.ai_guardrails.scan.policy import get_policy_value
-from cycode.cli.apps.ai_guardrails.scan.types import AiHookEventType, AIHookOutcome, BlockReason
+from cycode.cli.apps.ai_guardrails.scan.types import (
+ SECRETS_BLOCK_REASON_BY_EVENT_TYPE,
+ AiHookEventType,
+ AIHookOutcome,
+ BlockReason,
+)
 from cycode.cli.apps.ai_guardrails.scan.utils import is_denied_path, truncate_utf8
 from cycode.cli.apps.scan.code_scanner import _get_scan_documents_thread_func
 from cycode.cli.apps.scan.scan_parameters import get_scan_parameters
 from cycode.cli.cli_types import ScanTypeOption, SeverityOption
 from cycode.cli.files_collector.file_excluder import is_path_configured_in_exclusions
 from cycode.cli.models import Document
+from cycode.cli.utils.host_info import get_hostname, get_serial_number
 from cycode.cli.utils.progress_bar import DummyProgressBar, ScanProgressBarSection
 from cycode.cli.utils.scan_utils import build_violation_summary
 from cycode.logger import get_logger
 
 logger = get_logger('AI Guardrails')
 
-
 HandlerFn = Callable[[typer.Context, AIHookPayload, dict], HookDecision]
 
 
@@ -47,7 +52,7 @@ def handle_before_submit_prompt(ctx: typer.Context, payload: AIHookPayload, poli
  ai_client.create_event(payload, AiHookEventType.PROMPT, AIHookOutcome.ALLOWED)
  return HookDecision.allow(AiHookEventType.PROMPT)
 
-mode = get_policy_value(policy, 'mode', default=PolicyMode.BLOCK)
+effective_mode = get_effective_mode(policy, 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)
@@ -59,12 +64,18 @@ def handle_before_submit_prompt(ctx: typer.Context, payload: AIHookPayload, poli
  error_message = None
 
  try:
- violation_summary, scan_id = _scan_text_for_secrets(ctx, clipped, timeout_ms)
+ violation_summary, scan_id = _scan_text_for_secrets(
+ ctx,
+ clipped,
+ timeout_ms,
+ payload=payload,
+ event_type=AiHookEventType.PROMPT,
+ effective_mode=effective_mode,
+ )
 
  if violation_summary:
- block_reason = BlockReason.SECRETS_IN_PROMPT
- action = get_policy_value(prompt_config, 'action', default=PolicyMode.BLOCK)
- if action == PolicyMode.BLOCK and mode == PolicyMode.BLOCK:
+ block_reason = SECRETS_BLOCK_REASON_BY_EVENT_TYPE[AiHookEventType.PROMPT]
+ if effective_mode == GuardrailsMode.BLOCK:
  outcome = AIHookOutcome.BLOCKED
  user_message = f'{violation_summary}. Remove secrets before sending.'
  return HookDecision.deny(AiHookEventType.PROMPT, user_message)
@@ -97,9 +108,8 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
  ai_client.create_event(payload, AiHookEventType.FILE_READ, AIHookOutcome.ALLOWED)
  return HookDecision.allow(AiHookEventType.FILE_READ)
 
- mode = get_policy_value(policy, 'mode', default=PolicyMode.BLOCK)
  file_path = payload.file_path or ''
-action = get_policy_value(file_read_config, 'action', default=PolicyMode.BLOCK)
+effective_mode = get_effective_mode(policy, file_read_config)
 
  scan_id = None
  block_reason = None
@@ -110,7 +120,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 mode == PolicyMode.BLOCK and action == PolicyMode.BLOCK:
+ if effective_mode == GuardrailsMode.BLOCK:
  outcome = AIHookOutcome.BLOCKED
  user_message = f'Cycode blocked sending {file_path} to the AI (sensitive path policy).'
  return HookDecision.deny(
@@ -133,10 +143,12 @@ def handle_before_read_file(ctx: typer.Context, payload: AIHookPayload, policy:
  outcome = AIHookOutcome.ALLOWED
 
  if get_policy_value(file_read_config, 'scan_content', default=True):
- violation_summary, scan_id = _scan_path_for_secrets(ctx, file_path, policy)
+ violation_summary, scan_id = _scan_path_for_secrets(
+ ctx, file_path, policy, payload=payload, effective_mode=effective_mode
+ )
  if violation_summary:
- block_reason = BlockReason.SECRETS_IN_FILE
- if mode == PolicyMode.BLOCK and action == PolicyMode.BLOCK:
+ block_reason = SECRETS_BLOCK_REASON_BY_EVENT_TYPE[AiHookEventType.FILE_READ]
+ if effective_mode == GuardrailsMode.BLOCK:
  outcome = AIHookOutcome.BLOCKED
  user_message = f'Cycode blocked reading {file_path}. {violation_summary}'
  return HookDecision.deny(
@@ -191,7 +203,6 @@ class _ArgScanFeature:
  policy_key: str # 'mcp' or 'command_exec'
  scan_key: str # 'scan_arguments' or 'scan_command'
  event_type: AiHookEventType
- block_reason: BlockReason
  deny_message: Callable[[str], str]
  deny_agent_message: str
  ask_message: Callable[[str], str]
@@ -213,11 +224,10 @@ def _handle_arg_scan(
  ai_client.create_event(payload, feature.event_type, AIHookOutcome.ALLOWED)
  return HookDecision.allow(feature.event_type)
 
- mode = get_policy_value(policy, 'mode', default=PolicyMode.BLOCK)
  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)
-action = get_policy_value(feature_config, 'action', default=PolicyMode.BLOCK)
+effective_mode = get_effective_mode(policy, feature_config)
 
  scan_id = None
  block_reason = None
@@ -226,10 +236,17 @@ def _handle_arg_scan(
 
  try:
  if get_policy_value(feature_config, feature.scan_key, default=True):
- violation_summary, scan_id = _scan_text_for_secrets(ctx, clipped, timeout_ms)
+ 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 = feature.block_reason
- if mode == PolicyMode.BLOCK and action == PolicyMode.BLOCK:
+ 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,
@@ -275,7 +292,6 @@ def handle_before_mcp_execution(ctx: typer.Context, payload: AIHookPayload, poli
  policy_key='mcp',
  scan_key='scan_arguments',
  event_type=AiHookEventType.MCP_EXECUTION,
- block_reason=BlockReason.SECRETS_IN_MCP_ARGS,
  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.',
  ask_message=lambda v: f'{v} in MCP tool call "{tool}". Allow execution?',
@@ -295,6 +311,36 @@ 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 build_ai_guardrails_scan_parameters(
+ ctx: typer.Context,
+ paths: Optional[tuple[str, ...]],
+ payload: AIHookPayload,
+ event_type: AiHookEventType,
+ effective_mode: GuardrailsMode,
+) -> dict:
+ scan_parameters = get_scan_parameters(ctx, paths)
+ scan_parameters.setdefault('metadata', {})['ai_guardrails'] = {
+ 'mode': effective_mode.value,
+ 'ide_provider': payload.ide_provider,
+ 'detection_source': SECRETS_BLOCK_REASON_BY_EVENT_TYPE[event_type].value,
+ 'device_id': get_serial_number(),
+ 'device_hostname': get_hostname(),
+ 'conversation_id': payload.conversation_id,
+ 'generation_id': payload.generation_id,
+ 'ide_user_email': payload.ide_user_email,
+ 'mcp_server_name': payload.mcp_server_name,
+ 'mcp_tool_name': payload.mcp_tool_name,
+ }
+ return scan_parameters
+
+
 def _setup_scan_context(ctx: typer.Context) -> typer.Context:
  """Set up minimal context for scan_documents without progress bars or printing."""
  ctx.obj['progress_bar'] = DummyProgressBar([ScanProgressBarSection])
@@ -345,18 +391,32 @@ def _perform_scan(
  return None, scan_id
 
 
-def _scan_text_for_secrets(ctx: typer.Context, text: str, timeout_ms: int) -> tuple[Optional[str], Optional[str]]:
+def _scan_text_for_secrets(
+ ctx: typer.Context,
+ text: str,
+ timeout_ms: int,
+ payload: AIHookPayload,
+ event_type: AiHookEventType,
+ effective_mode: GuardrailsMode,
+) -> tuple[Optional[str], Optional[str]]:
  """Scan text content for secrets using Cycode CLI."""
  if not text:
  return None, None
 
  document = Document(path='prompt-content.txt', content=text, is_git_diff_format=False)
  scan_ctx = _setup_scan_context(ctx)
  timeout_seconds = timeout_ms / 1000.0
- return _perform_scan(scan_ctx, [document], get_scan_parameters(scan_ctx, None), timeout_seconds)
+ scan_parameters = build_ai_guardrails_scan_parameters(scan_ctx, None, payload, event_type, effective_mode)
+ return _perform_scan(scan_ctx, [document], scan_parameters, timeout_seconds)
 
 
-def _scan_path_for_secrets(ctx: typer.Context, file_path: str, policy: dict) -> tuple[Optional[str], Optional[str]]:
+def _scan_path_for_secrets(
+ ctx: typer.Context,
+ file_path: str,
+ policy: dict,
+ payload: AIHookPayload,
+ effective_mode: GuardrailsMode,
+) -> tuple[Optional[str], Optional[str]]:
  """Scan a file path for secrets."""
  if not file_path or not os.path.isfile(file_path):
  return None, None
@@ -375,4 +435,7 @@ def _scan_path_for_secrets(ctx: typer.Context, file_path: str, policy: dict) ->
 
  document = Document(path=os.path.basename(file_path), content=content, is_git_diff_format=False)
  scan_ctx = _setup_scan_context(ctx)
- return _perform_scan(scan_ctx, [document], get_scan_parameters(scan_ctx, (file_path,)), timeout_seconds)
+ scan_parameters = build_ai_guardrails_scan_parameters(
+ scan_ctx, (file_path,), payload, AiHookEventType.FILE_READ, effective_mode
+ )
+ return _perform_scan(scan_ctx, [document], scan_parameters, timeout_seconds)

cycode/cli/apps/ai_guardrails/scan/scan_command.py

@@ -8,6 +8,7 @@
 """
 
 from typing import Annotated, Optional, Union
+from uuid import uuid4
 
 import click
 import typer
@@ -125,6 +126,9 @@ def scan_command(
  return
 
  unified_payload = ide_integration.parse_hook_payload(payload)
+ if not unified_payload.generation_id:
+ # Not every IDE dialect provides a generation id (e.g. Copilot)
+ unified_payload.generation_id = str(uuid4())
  event_name = unified_payload.event_name
  logger.debug(
  'Processing AI guardrails hook',

cycode/cli/apps/ai_guardrails/scan/types.py

@@ -41,3 +41,12 @@ class BlockReason(StrEnum):
  SECRETS_IN_MCP_ARGS = 'secrets_in_mcp_args'
  SENSITIVE_PATH = 'sensitive_path'
  SCAN_FAILURE = 'scan_failure'
+
+
+# The reason each event type yields when a secret is found in it. Also travels with the scan as
+# `detection_source`, so the violation and the hook event are labelled from the same vocabulary.
+SECRETS_BLOCK_REASON_BY_EVENT_TYPE: dict[AiHookEventType, BlockReason] = {
+ AiHookEventType.PROMPT: BlockReason.SECRETS_IN_PROMPT,
+ AiHookEventType.FILE_READ: BlockReason.SECRETS_IN_FILE,
+ AiHookEventType.MCP_EXECUTION: BlockReason.SECRETS_IN_MCP_ARGS,
+}