SentraGuard Prompt Filter for Cursor

Overview

This extension configures the Cursor hook runner and ships a guardrail hook script that forwards validation requests to the extension bridge. The extension then validates prompts against the SentraGuard backend using extension settings. Legacy direct chat interception helpers have been removed; the Cursor hook runner + script/guardrail-hook.js + bridge server is the only supported integration path.

Installation (VSIX)

1. Build and package the extension:
   • npm run compile
   • npm run package
2. Install in Cursor:
   • cursor --install-extension sentraguard-cursor-0.0.1.vsix
   • Or Extensions panel -> ... -> Install from VSIX

Configuration

There are two configuration layers:

1. Cursor hook runner config (workspace root)

• Cursor reads only workspace-root .cursor/hooks.json
• The extension auto-creates or merges .cursor/hooks.json to run the guardrail script

2. Extension settings (recommended)

• sentra.apiUrl (default http://localhost:3001/api/v1)
• sentra.apiKey (required)
• sentra.timeoutMs (optional)
• sentra.failOpen (optional; default false)
• sentra.tamperMonitoring.enabled (optional; default true) — enable tamper detection for extension-managed files
• sentra.tamperMonitoring.remoteLogging (optional; default true) — send tamper events to the admin endpoint (POST {apiUrl}/tamper-events); when offline, events are queued and retried. When the extension is deactivated (uninstall, disable, or IDE shutdown), the admin is notified via POST {apiUrl}/extension-events with eventType: "DEACTIVATED" and device identification so admins know which device no longer has the extension.

Cursor hook runner auto-setup

• On activation, the extension ensures .cursor/hooks.json exists in the workspace root.
• It copies the hook script into the workspace at script/guardrail-hook.js.
• It writes Cursor hook runner schema (arrays of commands) to execute the workspace-local script:
  • beforeSubmitPrompt -> node script/guardrail-hook.js
  • preToolUse -> node script/guardrail-hook.js
• It writes .cursor/sentraguard.json with the local bridge port used by the hook script.
• If .cursor/hooks.json already exists, it merges by adding the missing command entries without overwriting existing ones.

Usage

• Cursor Chat (Ctrl+L / Cmd+L) and Composer (Ctrl+K / Cmd+K) are handled by the Cursor hook runner.
• Prompts are forwarded by script/guardrail-hook.js to the extension bridge before submission.
• The hook collects file context from @-mentions and path-like tokens in the prompt (including .json and .md), normalizes workspace paths on Windows, and sends it to the backend for validation.
• Warnings and blocks prevent submission by default (fail-closed).

For hook script details (stdin/output, file context, parsing, troubleshooting), see Guardrail Hook Script.

Tamper detection

The extension treats certain files it creates as system-controlled and monitors them for changes. Protected files are not read-only; users and the hook can edit them. Tamper detection is monitoring and alerting only.

• Protected files: .cursor/hooks.json, .cursor/sentraguard.json, script/guardrail-hook.js
• Detection: create, modify, delete, or rename of these files (outside extension-initiated updates) is reported as tampering.
• On tamper: a warning notification is shown, the event is logged to the SentraGuard output channel and to a persistent tamper log, and (if sentra.tamperMonitoring.remoteLogging is true) the event is sent to the admin endpoint or queued when offline. Each event sent to the admin includes device identification (machineId, hostname, platform) so admins can see which device the tampering occurred on.
• Commands: SentraGuard: Show Tamper Log opens the list of recent tamper events.

Baseline hashes are stored per-workspace in the extension’s workspace state. Extension writes (e.g. during setup or Force Initialize) are marked as trusted so they do not trigger alerts. When the user uninstalls, disables, or closes the IDE, the extension sends a DEACTIVATED event to the admin endpoint (if remote logging is enabled) so admins can see which device stopped running the extension.

Logging

Open Output panel (View -> Output) and choose "SentraGuard". Logs are redacted and only include prompt hash and length, never full prompt text. Tamper events are also written there and to the tamper log.

Troubleshooting

• Missing API key: set sentra.apiKey in extension settings.
• Backend offline: blocked unless sentra.failOpen is true.
• Timeout: adjust sentra.timeoutMs.
• Tamper alerts for your own edits: only changes made outside the extension (e.g. editing .cursor/hooks.json by hand) are flagged; extension writes during setup or Force Init are trusted. To disable tamper monitoring, set sentra.tamperMonitoring.enabled to false.

Security

Prompts are sent to the backend for validation. Logs are redacted (hash + length only). Extension-managed files are monitored for tampering; do not disable tamper monitoring in high-assurance environments.

Compatibility

Works in Cursor IDE and VS Code. Hooks are a Cursor feature and only run when a workspace has .cursor/hooks.json at its root.