AI Guard Checkpoint Node for n8n

Protect your LLM workflows from prompt injection, data leakage, and policy violations. This n8n community node integrates AI Guard's real-time checkpoint evaluation directly into your n8n pipelines.

Description

The AI Guard Checkpoint node evaluates prompts, model outputs, and tool calls against configurable security policies before they reach your LLM or your users. Each checkpoint returns an allow/block decision with a risk score, severity level, and detailed findings, enabling you to branch workflow execution based on security risk.

Key capabilities

• Prompt checkpoints: Scan user input for prompt injection, jailbreaking, and policy violations before sending to an LLM.
• Output checkpoints: Scan model responses for disallowed content, data leakage, and policy violations before returning to the user.
• Tool checkpoints: Validate tool invocations (name, arguments, target) before execution.
• Policy enforcement modes: Observe (log only), Shadow Block (simulate blocking), or Enforce (actually block).
• Fail-open safety: Configurable fail-open behavior ensures your workflows continue even if the checkpoint service is unreachable.
• Automatic retries: Transient failures (rate limits, server errors, network blips) are automatically retried with exponential backoff.

Requirements

• n8n 1.90.0 or later (for community node support)
• AI Guard API access: A running AI Guard API instance (hosted or self-hosted) with valid API credentials.
• Node.js 18+ for local development and building.

Installation

Option 1: Install from the n8n Community Registry (recommended)

1. In n8n, go to Settings > Community Nodes.
2. Click Install.
3. Enter @scan5/ai-guard-n8n-node and click Install.
4. After installation, restart n8n if prompted.

Option 2: Manual install from source

# Clone the repository
git clone https://github.com/wangai003/scan5.git
cd scan5/packages/ai-guard-n8n-node

# Install dependencies and build
npm install
npm run build

# Copy or symlink the dist folder to your n8n custom nodes directory
# macOS/Linux:
cp -r dist ~/.n8n/custom/nodes/ai-guard-n8n-node/
# Windows (PowerShell):
# Copy-Item -Recurse dist $env:USERPROFILE\.n8n\custom\nodes\ai-guard-n8n-node\

# Restart n8n

Credentials setup

Before using the node, create an AI Guard API credential in n8n:

1. Go to Settings > Credentials in n8n.
2. Click Add Credential and search for "AI Guard API".
3. Fill in the fields:

| Field | Description | Default | |-------|-------------|---------| | API Base URL | The AI Guard API endpoint | https://scan5.vercel.app | | API Key | Your AI Guard API bearer token | (required) | | Workspace ID | Your AI Guard workspace identifier | (required) |

API keys and workspaces are created and managed in the AI Guard dashboard. For self-hosted deployments, set the API Base URL to your instance (e.g., http://localhost:8080).

Node configuration

| Field | Description | Default | |-------|-------------|---------| | Checkpoint Kind | Prompt, Output, or Tool | Prompt | | Workflow ID | Unique workflow identifier (required) | -- | | Step Name | Logical step (e.g., "pre-llm", "post-llm") | "pre-llm" | | Policy Mode | Observe (log), Shadow Block (simulate), or Enforce | Observe | | Severity Threshold | Minimum severity to act on | None | | Fail Open | Allow operation if service is unreachable | true | | Redaction Toggle | Auto-redact PII/secrets in audit logs | true | | Capture Payloads | Store full inputs in audit log | false | | Context (JSON) | Extra metadata as JSON object | {} |

Checkpoint-specific fields

• Prompt kind: Requires the Prompt text field.
• Output kind: Requires the Output Text field.
• Tool kind: Requires Tool Name and optional Tool Arguments (JSON) and Tool Target.

Output fields

The node outputs the following fields on each item for use in downstream IF nodes or transformations:

| Field | Type | Description | |-------|------|-------------| | allow | boolean | true if safe to proceed, false if blocked | | action | string | Decision: allow, review, or block | | riskScore | number | 0-100 risk score (higher = more risky) | | severity | string | low, medium, high, or critical | | reason | string | Human-readable explanation of the decision | | matchedRuleIds | string[] | IDs of the security rules that triggered | | findings | object[] | Detailed finding objects with rule metadata | | checkpointId | string | Unique checkpoint event identifier | | traceId | string | Trace ID for distributed correlation |

Example workflow

An import-ready example workflow is available at examples/workflow-ai-guard-checkpoint.json.

The basic pattern is:

[Trigger] -> [AI Guard Checkpoint] -> [IF allow === true] -> [Continue to LLM]
                                              |
                                              +-> [Escalate / Block]

Minimal prompt checkpoint

1. Add a Manual Trigger node.
2. Add the AI Guard Checkpoint node.
3. Set Checkpoint Kind to "Prompt".
4. Set Prompt to {{ $json.userPrompt }}.
5. Set Workflow ID to your workflow name.
6. Add an IF node after the checkpoint.
7. In the IF node, set condition: {{ $json.allow }} equals true.
8. Connect the "true" branch to your LLM node and the "false" branch to a block/escalation handler.

Error handling

The node provides descriptive error messages for common failure modes:

• 401 Unauthorized: The API key is invalid. Check the credential settings.
• 404 Workspace Not Found: The workspace ID doesn't exist. Verify it in the credential settings.
• 429 Rate Limited: Too many requests. Reduce workflow concurrency or upgrade your plan.
• Connection refused: The API Base URL is incorrect or the service is down.
• Request timeout: The API did not respond in time. Check service health.

Network and server errors are automatically retried up to 3 times with exponential backoff (1s, 2s, 4s). If all retries fail, the node reports the error after the final attempt.

Set Fail Open to true to allow workflow execution to continue if the checkpoint service is unreachable.

Troubleshooting

Node not appearing in the palette: Verify the node is installed under Settings > Community Nodes. If manually installed, confirm the dist folder exists and contains the compiled JavaScript files.

"Credentials not found" error: Ensure you've created an AI Guard API credential (Settings > Credentials) and selected it on the node.

API connection errors: Verify the API Base URL is correct and reachable from your n8n instance. For self-hosted AI Guard, confirm the server is running.

Resources

• AI Guard GitHub Repository
• AI Guard Documentation
• Report an Issue
• n8n Community Nodes Documentation