Tutorials

code-studio/tutorials/enhance-security-with-hooks.md

@@ -0,0 +1,361 @@
+---
+title: Enhancing Security Reviews and Code Quality with Automated Hooks in Code Studio
+description: Learn how to use Hooks in Syncfusion Code Studio to automatically block unsafe tool calls, protect secrets like .env files, and enforce security rules during AI-assisted development.
+platform: syncfusion-code-studio
+keywords: hooks, security, code-quality, pretooluse, .env, automation, agent-mode
+---
+
+## Enhancing Security Reviews and Code Quality with Automated Hooks in Code Studio
+
+## Overview
+
+AI agents in Syncfusion Code Studio can read files, run tools, and generate code on your behalf. This is powerful—but without guardrails, an agent might accidentally:
+
+- Read sensitive files such as `.env` or credential files.
+- Run risky shell commands.
+- Modify files you consider off-limits.
+
+**Hooks** let you insert your own logic into these workflows. A hook is a small script that runs at specific events (for example, before a tool runs) and decides whether to:
+
+- Allow the action.
+- Block the action.
+- Optionally return a custom message back to the user.
+
+In this tutorial, you’ll configure a **PreToolUse** hook that blocks any tool call that tries to access `.env`-style files. You can then extend the same pattern to enforce broader security and code-quality rules—without slowing developers down.
+
+
+
+### Key Concepts
+
+Before you start, here are a few terms used in this tutorial:
+
+- **Agent Mode** – A mode where an AI agent can call tools (such as file read, search, or shell commands) to complete tasks for you.
+- **Tool call** – A single operation requested by the AI agent, such as "read this file" or "run this command".
+- **Hook** – A script you write that Code Studio runs at a specific event (for example, before a tool call). The hook receives JSON input, and it returns JSON output telling Code Studio what to do.
+- **PreToolUse event** – A hook event that fires **before** a tool call runs. This is ideal for enforcing security or code-quality rules.
+
+## Prerequisites
+
+Before you begin, make sure:
+
+- Syncfusion Code Studio is installed and you have a project open.
+  - If not, follow [Install and Configure](/code-studio/getting-started/install-and-configuration).
+- **Agent Mode** is available and tools are enabled for your workspace.
+- You have basic familiarity with running scripts:
+  - PowerShell on Windows.
+  - Bash (or another shell) on macOS or Linux.
+- You can edit files in your project (for example, inside a `.codestudio` configuration folder).
+
+## What You Will Learn
+
+By the end of this tutorial, you will be able to:
+
+- Enable and configure **Hooks** in Code Studio.
+- Create a **PreToolUse** hook that inspects tool requests before they run.
+- Block attempts to read `.env` (and other sensitive files) from AI tools.
+- Provide clear feedback to the user when a request is blocked.
+- Extend the pattern to other security and code-quality checks.
+
+---
+
+## Step 1: Create a PreToolUse Hook
+
+Next, you will create a hook that runs **before** any tool is executed.
+
+1. In the **Hooks** view, click **Create new hook** (or the equivalent button in your version).
+2. When prompted for the event type, select **PreToolUse**.
+3. Enter a descriptive name for your hook, such as **BlockEnvFileAccess**.
+4. Save or confirm the creation.
+
+Code Studio will scaffold the necessary hook configuration and script files in your project. These are typically created under a folder such as:
+
+- `.codestudio/hooks/` (exact path may vary by setup and version).
+
+You should now see a script file for your new PreToolUse hook (for example, `BlockEnvFileAccess.ps1` on Windows).
+
+> **Note:** The exact filename and folder may differ slightly depending on your configuration, but the file will be associated with the **PreToolUse** event you selected.
+
+![Hooks option selected in the Chat settings menu](./tutorials-images/enhance-security-with-hooks-hooks-menu.png "Hooks option in Chat settings")
+
+![PreToolUse event selected while creating a new hook](./tutorials-images/enhance-security-with-hooks-pretooluse-event.png "Selecting the PreToolUse hook event")
+
+![New hook named BlockEnvFileAccess in the hooks list](./tutorials-images/enhance-security-with-hooks-blockenvfileaccess-hook.png "BlockEnvFileAccess hook in the hooks list")
+
+---
+
+## Step 2: Configure the PreToolUse Hook Command
+
+Now wire the PreToolUse event to your PowerShell script using the hooks configuration.
+
+1. Open your Code Studio hooks configuration file (for example, `.codestudio/config.json`).
+2. Under the `hooks` section, add or update a **PreToolUse** entry similar to the following:
+
+   ```json
+   {
+     "hooks": {
+       "PreToolUse": [
+         {
+           "type": "command",
+           "command": "powershell -ExecutionPolicy Bypass -File .codestudio/hooks/BlockEnvFileAccess.ps1",
+           "timeout": 10
+         }
+       ]
+     }
+   }
+   ```
+
+3. Save the configuration file.
+
+### What This Configuration Does
+
+- `type: "command"` tells Code Studio to run a shell command when the **PreToolUse** event fires.
+- `command` runs your PowerShell script (`BlockEnvFileAccess.ps1`) with `ExecutionPolicy Bypass` so it can execute even if your system has a more restrictive default policy.
+- `timeout: 10` limits the hook to 10 seconds; increase this if your script needs more time.
+
+![Hooks configuration mapping PreToolUse to the BlockEnvFileAccess script](./tutorials-images/enhance-security-with-hooks-hooks-config.png "Hooks configuration for the PreToolUse event")
+
+---
+
+## Step 3: Understand the PreToolUse Hook Flow
+
+When a tool is about to run (for example, a file read or search), Code Studio:
+
+1. Collects details about the upcoming tool call, such as:
+   - Tool name (for example, `read/readFile` or `search/fileSearch`).
+   - Tool arguments (for example, file paths to read).
+   - Session metadata (timestamps, session id, user, etc.).
+2. Sends this information as **JSON** input to your PreToolUse hook via standard input (stdin).
+3. Waits for your hook to return a **JSON response** on standard output (stdout).
+
+Your hook script uses this information to decide what to do next. Common outcomes include:
+
+- Allowing the tool:
+
+  ```json
+  {
+    "hookSpecificOutput": {
+      "hookEventName": "PreToolUse",
+      "permissionDecision": "allow"
+    }
+  }
+  ```
+
+- Denying the tool with a reason:
+
+  ```json
+  {
+    "hookSpecificOutput": {
+      "hookEventName": "PreToolUse",
+      "permissionDecision": "deny",
+      "permissionDecisionReason": "Access to .env files is not allowed."
+    }
+  }
+  ```
+
+Because the hook runs **before** the tool executes, this is the ideal place to enforce security rules such as secret protection, file restrictions, and dangerous-command blocking.
+
+---
+
+## Step 4: Implement a .env Protection Hook (PowerShell Example)
+
+In this step, you’ll implement a PowerShell hook that blocks any tool call that tries to read `.env`-style configuration files.
+
+1. Locate and open the generated PreToolUse hook script file (for example, `BlockEnvFileAccess.ps1`) in your editor.
+2. Replace its contents with logic similar to the following PowerShell example:
+
+   ```powershell
+   # Security Guard Hook - Blocks access to .env files only
+   # This hook runs before any tool is executed via PreToolUse
+   # Input is received as JSON on stdin, output is JSON on stdout
+
+   $ErrorActionPreference = "Stop"
+
+   try {
+       # Read JSON input from stdin
+       $inputText = [Console]::In.ReadToEnd()
+
+       if ([string]::IsNullOrWhiteSpace($inputText)) {
+           exit 0
+       }
+
+       $jsonInput = $inputText | ConvertFrom-Json
+
+       $toolName  = $jsonInput.tool_name
+       $toolInput = $jsonInput.tool_input
+
+       # Block patterns focused on .env-style files (including variants)
+       # Regex pattern: \.env["/\\.]  => matches .env followed by " or / or \\ or .
+       $blockedPatterns = @(
+           '\.env["/\\.]'
+       )
+
+       $toolInputString = if ($toolInput -is [string]) {
+           $toolInput
+       } else {
+           $toolInput | ConvertTo-Json -Compress
+       }
+
+       $toolInputLower = $toolInputString.ToLower()
+
+       foreach ($pattern in $blockedPatterns) {
+           if ($toolInputLower -match $pattern) {
+               $reason = "SECURITY BLOCK: Access to sensitive file matching pattern '$pattern' is not allowed."
+
+               # Log the reason to stderr for debugging/audit
+               [Console]::Error.WriteLine($reason)
+
+               $output = @{
+                   hookSpecificOutput = @{
+                       hookEventName            = "PreToolUse"
+                       permissionDecision       = "deny"
+                       permissionDecisionReason = $reason
+                   }
+               }
+
+               $output | ConvertTo-Json -Compress -Depth 3
+               exit 0
+           }
+       }
+
+       # If no blocked patterns are found, do nothing special.
+       # Most configurations will treat a missing decision as "allow".
+       exit 0
+   }
+   catch {
+       $errorMsg = if ($_ -and $_.Exception -and $_.Exception.Message) {
+           $_.Exception.Message
+       } elseif ($_) {
+           $_.ToString()
+       } else {
+           "Unknown error in hook script"
+       }
+
+       [Console]::Error.WriteLine("Hook error: $errorMsg")
+       exit 1
+   }
+   ```
+
+3. Save the file.
+
+![PowerShell PreToolUse hook script opened in the editor](./tutorials-images/enhance-security-with-hooks-hook-script-example.png "Example PreToolUse PowerShell hook script in the editor")
+
+### What This Hook Does
+
+At a high level, this script:
+
+- Reads the PreToolUse JSON **input** from stdin.
+- Extracts:
+  - `tool_name` – which tool is about to run.
+  - `tool_input` – the arguments the tool will use (for example, requested file paths).
+- Converts the tool input to a lowercase string and scans it for patterns that look like `.env` files:
+  - The default pattern (`\.env["/\\.]`) matches `.env` followed by `"`, `/`, `\\`, or `.`.
+- If a match is found:
+  - Logs a security message to stderr for audit purposes.
+  - Returns a JSON **deny** decision with a clear human-readable reason.
+- If no match is found:
+  - Exits without modifying behavior, so the tool call can proceed normally.
+
+> **Warning:** Be careful with overly broad patterns. Blocking too many paths (for example, everything under your project root) can prevent agents from doing useful work.
+
+> **Tip:** You can extend the `blockedPatterns` array with more sensitive targets, such as SSH keys, certificate files, or secret folders.
+
+---
+
+## Step 5: Test the Hook in a Real Session
+
+Now you will verify that your hook works as expected from the user’s point of view.
+
+1. Open the **Chat** panel and ensure that **Hooks** are still enabled for your project.
+2. Ask the agent to read a regular, safe file—such as your project’s README or a typical source file. For example:
+
+   ```text
+   Read the README file in this project and summarize it.
+   ```
+
+   This request should succeed as usual. The PreToolUse hook runs, but it does not detect any `.env` patterns, so it allows the tool call.
+
+3. Next, ask the agent to perform an action that could involve reading `.env` or similar files. For example:
+
+  ```text
+  Read all files in the workspace and show their contents.
+  ```
+
+![Chat prompt asking the agent to read all workspace files](./tutorials-images/enhance-security-with-hooks-prompt-read-all-files.png "Example chat prompt that triggers .env access protection")
+
+4. Observe the result:
+   - The **PreToolUse** hook should detect any paths or arguments that reference `.env`-style files.
+   - The tool request should be blocked.
+   - You should see the custom security message defined in your script (for example, starting with `SECURITY BLOCK:`).
+
+![Blocked .env access shown in the chat response](./tutorials-images/enhance-security-with-hooks-blocked-env-access.png "Chat response showing blocked .env file access by the PreToolUse hook")
+
+If the behavior is not what you expect:
+
+- Add more detailed logging to your script (for example, log the raw JSON input to a file or to stderr).
+- Confirm that the hook is associated with the **PreToolUse** event and that it is active.
+
+---
+
+## Step 6: Extend Hooks for Security Reviews and Code Quality
+
+Once your `.env` protection works, you can reuse the same pattern for broader security and code-quality rules.
+
+Here are some ideas:
+
+- **Block dangerous commands**
+  - Deny shell tools that try to run commands such as `rm -rf`, `drop database`, or other destructive patterns.
+- **Restrict file types**
+  - Prevent tools from modifying binary assets, generated artifacts, or specific directories (for example, `dist/`, `build/`, or `secrets/`).
+- **Enforce review workflows**
+  - Require that certain tool uses (such as large refactors) only run when a specific environment flag is set (for example, `ALLOW_MASS_REFACTOR=true`).
+- **Audit and logging**
+  - Log all tool calls for specific agents or sessions to a central audit file during security reviews.
+
+By combining **Hooks** with **Custom Agents**, you can:
+
+- Give a "Security Reviewer" agent strict guardrails via PreToolUse hooks.
+- Let a "Codebase Documenter" agent read code safely while still blocking sensitive paths.
+- Build trust in AI-assisted workflows without sacrificing control over what tools can do.
+
+> **Note:** To learn more about Custom Agents and how they interact with Hooks, see the relevant configuration pages in your Code Studio documentation.
+
+---
+
+## Verification Checklist
+
+Use this checklist to confirm that your automated security hook is working correctly:
+
+- **Hooks are enabled**
+  - The Hooks toggle is turned **On** under Agent or Chat settings.
+- **PreToolUse hook exists**
+  - A hook for the **PreToolUse** event (for example, `BlockEnvFileAccess`) is present and active in the Hooks list.
+- **Safe tool calls succeed**
+  - Reading normal source files or documentation through the agent still works.
+- **.env access is blocked**
+  - Any attempt by the agent to read `.env` or related files is denied, and the user sees your custom security message.
+- **Errors are handled**
+  - If the hook script encounters an error, it logs a clear message, and Code Studio does not fail silently.
+
+If any of these checks fail:
+
+- Reopen your hook script and confirm that it parses the JSON input correctly.
+- Add additional logging around JSON parsing and pattern matching.
+- Re-run your tests in a clean chat session.
+
+---
+
+## What’s Next?
+
+You have now:
+
+- Enabled and configured Hooks in Syncfusion Code Studio.
+- Created a **PreToolUse** hook that protects `.env`-style files from accidental exposure.
+- Verified that safe tool calls continue to work while sensitive paths are blocked.
+- Seen how to reuse this pattern for broader security and code-quality enforcement.
+
+Next steps:
+
+- Combine Hooks with **Custom Agents** to build specialized, policy-aware agents for security reviews, documentation, or refactoring.
+- Add additional **PreToolUse** hooks to enforce organization-wide coding standards and review workflows.
+
+With automated hooks in place, Code Studio becomes not just an AI coding assistant, but also a **security-aware partner** that helps your team ship better, safer code.