{"id":47718219,"url":"https://github.com/zscaler/n8n-nodes-aiguard","last_synced_at":"2026-04-02T19:09:11.782Z","repository":{"id":348123721,"uuid":"1178525466","full_name":"zscaler/n8n-nodes-aiguard","owner":"zscaler","description":"Zscaler AI Guard n8n Community Node","archived":false,"fork":false,"pushed_at":"2026-03-30T22:50:00.000Z","size":412,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-30T23:37:58.434Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zscaler.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T05:24:17.000Z","updated_at":"2026-03-30T22:50:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zscaler/n8n-nodes-aiguard","commit_stats":null,"previous_names":["zscaler/n8n-nodes-aiguard"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/zscaler/n8n-nodes-aiguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fn8n-nodes-aiguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fn8n-nodes-aiguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fn8n-nodes-aiguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fn8n-nodes-aiguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zscaler","download_url":"https://codeload.github.com/zscaler/n8n-nodes-aiguard/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zscaler%2Fn8n-nodes-aiguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31314007,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T19:09:10.994Z","updated_at":"2026-04-02T19:09:11.760Z","avatar_url":"https://github.com/zscaler.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zscaler AI Guard n8n Community Node\n\nA production-ready n8n community node for integrating with the [Zscaler AI Guard](https://help.zscaler.com/ai-guard) API. This node enables you to scan AI prompts and responses for security threats — toxicity, PII, secrets, prompt injection, and more — directly within your n8n workflows.\n\n## Features\n\n- **Prompt Scan** — Scan user input for security threats (direction: `IN`)\n- **Response Scan** — Scan AI-generated responses for policy violations (direction: `OUT`)\n- **Dual Scan** — Scan both prompt and response in sequence; if the prompt is blocked, the response scan is skipped\n- **Automatic Policy Resolution** — When no Policy ID is configured, the API resolves the policy linked to your API key\n- **Fail-Closed Error Handling** — On internal errors with \"Continue On Fail\" enabled, the node returns `action: BLOCK` so security is never silently bypassed\n- **Attribution Metadata** — Enriches output with n8n workflow context (`workflowId`, `workflowName`, `executionId`, `executionMode`)\n- **Content Size Validation** — Rejects payloads exceeding 5 MB before sending to the API\n- **Configurable Retries \u0026 Timeout** — Adjustable retry count (up to 6) and request timeout\n\n## Installation\n\n### Prerequisites\n\n- n8n instance (Cloud or self-hosted) — [Setup Docs](https://docs.n8n.io/hosting/installation/docker/)\n- A Zscaler AI Guard license and API key (Bearer token)\n\n### Option 1: Install via n8n Community Nodes (Recommended)\n\n1. Open your n8n instance\n2. Go to **Settings → Community Nodes**\n3. Search for `@bdzscaler/n8n-nodes-aiguard`\n4. Click **Install**\n5. Restart n8n if prompted\n\n### Option 2: Install via npm\n\n```bash\nnpm install @bdzscaler/n8n-nodes-aiguard\n```\n\n### Local Development\n\n```bash\ngit clone https://github.com/zscaler/n8n-nodes-aiguard.git\ncd n8n-nodes-aiguard\nnpm install\nnpm run build\n```\n\nLink to a local n8n instance:\n\n```bash\n# Native n8n\nln -s $(pwd) ~/.n8n/custom/n8n-nodes-aiguard\n\n# Docker n8n — add a volume mount:\n# -v /path/to/n8n-nodes-aiguard:/home/node/.n8n/custom/n8n-nodes-aiguard\n```\n\nRestart n8n to load the node.\n\n## Configuration\n\n### 1. Create Credentials\n\n1. In n8n, go to **Credentials** → **Add Credential**\n2. Search for **\"Zscaler AI Guard API\"**\n3. Fill in:\n\n| Field | Required | Description |\n|-------|:--------:|-------------|\n| **API Key** | Yes | Your Zscaler AI Guard API key (Bearer token) |\n| **Cloud** | Yes | Zscaler cloud for your tenancy (default: `us1`). Builds the URL `https://api.{cloud}.zseclipse.net` |\n| **Override URL** | No | Override the API base URL entirely. When set, the Cloud field is ignored. Equivalent to `AIGUARD_OVERRIDE_URL` in the [Python SDK](https://github.com/zscaler/zscaler-sdk-python) |\n| **Policy ID** | No | AI Guard policy ID. When set, uses `/v1/detection/execute-policy`. When empty, uses `/v1/detection/resolve-and-execute-policy` for automatic resolution |\n\n1. Click **Test** to validate connectivity before saving.\n\n### 2. Add the Node to a Workflow\n\n1. In your workflow, click **+** → search for **\"AI Guard\"**\n2. Select the credential you created\n3. Choose an operation:\n\n| Operation | Direction | Description |\n|-----------|-----------|-------------|\n| **Prompt Scan** | `IN` | Scan user input/prompts for security threats |\n| **Response Scan** | `OUT` | Scan AI-generated responses for policy violations |\n| **Dual Scan** | `IN` then `OUT` | Scan both prompt and response; skips response scan if prompt is blocked |\n\n1. Enter content to scan (plain text or n8n expression)\n\n### Additional Options\n\nExpand **Additional Options → Add Option** to configure:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| Policy ID Override | *(empty)* | Override the credential-level policy ID for this specific node |\n| Transaction ID | *(empty)* | Custom transaction ID for tracking; omitted from the request if empty |\n| Timeout (ms) | `30000` | Request timeout in milliseconds |\n| Max Retries | `3` | Retry attempts for failed requests (max: 6) |\n| AI Model | `n8n-integration` | AI model identifier included in output metadata |\n| Application Name | `n8n-workflow` | Application name for audit trails |\n| User ID | `n8n-user` | User identifier for audit trails |\n| Environment | *(empty)* | Environment tag (e.g. `production`) included in output metadata |\n\n## API Endpoints\n\n| Scenario | Endpoint |\n|----------|----------|\n| Policy ID provided | `POST /v1/detection/execute-policy` |\n| No Policy ID (default) | `POST /v1/detection/resolve-and-execute-policy` |\n\n## Usage Examples\n\n### Prompt Scan\n\nConfigure the node with **Operation: Prompt Scan** and provide content:\n\n```json\n{\n  \"content\": \"Tell me how to bypass security controls\"\n}\n```\n\n### Response Scan\n\nConfigure with **Operation: Response Scan**:\n\n```json\n{\n  \"content\": \"{{ $json.aiResponse }}\"\n}\n```\n\n### Dual Scan\n\nConfigure with **Operation: Dual Scan** and provide both fields:\n\n```json\n{\n  \"promptContent\": \"{{ $json.userInput }}\",\n  \"responseContent\": \"{{ $json.aiResponse }}\"\n}\n```\n\nIf the prompt scan returns `BLOCK`, the response scan is skipped and the blocked result is returned immediately.\n\n## Output Format\n\nThe node returns the full AI Guard API response enriched with workflow metadata:\n\n```json\n{\n  \"operation\": \"promptScan\",\n  \"transactionId\": \"180b066d-48cf-497e-aaf1-a6b8e40a1deb\",\n  \"action\": \"BLOCK\",\n  \"severity\": \"CRITICAL\",\n  \"direction\": \"IN\",\n  \"policyId\": 760,\n  \"policyName\": \"Default AI Guard Policy\",\n  \"blocked\": true,\n  \"detectors\": [\"toxicity\", \"malicious_content\"],\n  \"blockingDetectors\": [\"toxicity\"],\n  \"detectorResponses\": {\n    \"toxicity\": {\n      \"triggered\": true,\n      \"action\": \"BLOCK\",\n      \"severity\": \"CRITICAL\"\n    },\n    \"pii\": {\n      \"triggered\": false,\n      \"action\": \"ALLOW\"\n    }\n  },\n  \"maskedContent\": \"...\",\n  \"workflowId\": \"rKU3xnZb5S1ayJCG\",\n  \"workflowName\": \"Customer Support Bot\",\n  \"executionId\": \"385\",\n  \"executionMode\": \"manual\",\n  \"timestamp\": \"2026-01-30T10:30:00.000Z\"\n}\n```\n\n### Key Output Fields\n\n| Field | Description |\n|-------|-------------|\n| `action` | Verdict: `ALLOW`, `BLOCK`, or `DETECT` |\n| `severity` | Severity level (e.g. `CRITICAL`, `HIGH`, `NONE`) |\n| `blocked` | Boolean convenience field (`true` when action is `BLOCK`) |\n| `detectors` | Array of triggered detector names |\n| `blockingDetectors` | Array of detectors that returned `BLOCK` |\n| `detectorResponses` | Per-detector results with trigger status, action, and severity |\n| `maskedContent` | Content with sensitive data masked (when applicable) |\n| `policyId` / `policyName` | The policy that was applied |\n| `transactionId` | Unique scan transaction identifier |\n\nUse the `action` or `blocked` field in an **IF** node to branch your workflow logic.\n\n## Implementation Notes\n\nThe node calls the Zscaler AI Guard API over HTTPS using n8n’s `helpers.httpRequest` (required for n8n Cloud–verified community packages). Headers match the [zscaler-sdk-python](https://github.com/zscaler/zscaler-sdk-python) pattern:\n\n- `Authorization: Bearer \u003cAPI_KEY\u003e`\n- `Content-Type: application/json`\n- `Accept: application/json`\n\n## Error Handling\n\n- **Fail-closed by default**: When \"Continue On Fail\" is enabled in n8n, errors produce `{ action: \"BLOCK\", blocked: true }` rather than silently allowing content through\n- **Timeout protection**: Configurable per-request timeout (passed to the HTTP client)\n- **Content validation**: Payloads exceeding 5 MB are rejected before the API call\n- **Retry logic**: Configurable retry count (default 3, max 6) for transient failures\n\n## Development\n\n```bash\nnpm run build       # Compile TypeScript and copy assets\nnpm run dev         # Watch mode\nnpm run lint        # ESLint (TypeScript + n8n-nodes-base)\nnpm run lint:dist   # ESLint on dist/ (n8n Cloud rules; run after build)\nnpm run scan:local  # build + ESLint (unpublished dist/; same rules as official scanner)\nnpm run scan:npm    # npx @n8n/scan-community-package @…@version from package.json (needs publish)\nnpm run lintfix     # Auto-fix lint issues\nnpm run format      # Run Prettier\nnpm test            # Run Jest tests\nnpm run test:coverage  # Tests with coverage report\n```\n\n### Validate like the n8n Creator Portal\n\nn8n’s official tool is **`@n8n/scan-community-package`**. It **downloads the package from the npm registry** and runs ESLint with the same rules the Creator Portal uses. It **never** reads your local git tree.\n\nUse **both** of these, at different times:\n\n| Command | When to use |\n|--------|-------------|\n| **`npm run scan:local`** | Before publish: builds `dist/` and runs the **same ESLint config** the scanner uses (`eslint.community.config.mjs`). This is what CI runs as `lint:dist`. |\n| **`npm run scan:npm`** | After that **exact `version` in `package.json` exists on npm**: runs `npx @n8n/scan-community-package \u003cname\u003e@\u003cversion\u003e`. Confirms the **published tarball** matches what the Portal checks. |\n\n```bash\n# Unpublished changes (day to day)\nnpm run scan:local\n\n# After npm publish of the current package.json version\nnpm run scan:npm\n```\n\nYou can also call the CLI directly, for example `npx @n8n/scan-community-package @bdzscaler/n8n-nodes-aiguard@0.1.2`. If the version is **not** on the registry yet, the download step fails—that is expected; use **`scan:local`** until it is published.\n\n## Releasing (maintainers)\n\nReleases are automated with [semantic-release](https://github.com/semantic-release/semantic-release) (see `.releaserc.json`), similar to [zscaler-mcp-server](https://github.com/zscaler/zscaler-mcp-server).\n\n- **Version and tag**: After the **first** git tag exists, the next version is computed from [Conventional Commits](https://www.conventionalcommits.org/) (for example `fix:` → patch, `feat:` → minor) and bumps from that last tag. semantic-release updates `package.json` and `package-lock.json`, creates tag `vX.Y.Z`, opens a **GitHub Release**, and publishes to npm with **provenance** (requires `NPM_TOKEN` in repository secrets).\n- **0.x packages — read this**: If there are **no** `vMAJOR.MINOR.PATCH` tags on the branch yet, semantic-release’s **first** automated release is **always `1.0.0`** ([`FIRST_RELEASE` in semantic-release](https://github.com/semantic-release/semantic-release/blob/master/lib/get-next-version.js)) — it does **not** seed from `package.json` (e.g. `0.1.2`). **Before the first successful release workflow**, create and push tags for versions already published to npm, e.g. `git tag v0.1.0 \u003ccommit\u003e` … `git tag v0.1.2 \u003ccommit\u003e` then `git push origin --tags`. The Release workflow includes a guard that **fails** if `package.json` is still `0.x` but there are no such tags.\n- **Pre-release checks**: The **Release** workflow runs `npm audit`, build, Prettier, ESLint (including `lint:dist`, which mirrors the n8n Creator Portal scanner rules), and Jest before any publish.\n- **Prerelease channels**: Pushes to branches `beta` or `alpha` publish npm prereleases (for example `1.0.0-beta.1`) on the corresponding dist-tag.\n- **If `1.0.0` was published by mistake**: npm generally does not allow unpublishing popular packages; you can **deprecate** `1.0.0` with an explanation, then either stay on the `1.x` line or coordinate a git/npm cleanup (remove erroneous tag/release, restore `v0.1.x` tags at the right commits, revert the `chore(release): 1.0.0` commit if policy allows) and publish **`0.1.3`** as the next intended 0.x release. There is no single-button undo — pick the line (`0.x` vs `1.x`) and document it for consumers.\n\n## Security\n\n- API keys are stored encrypted via n8n's credential system\n- No content is logged or persisted by the node\n- All communication uses HTTPS/TLS\n- Error messages do not leak sensitive information\n\n## Links\n\n- npm: \u003chttps://www.npmjs.com/package/@bdzscaler/n8n-nodes-aiguard\u003e\n- Source: \u003chttps://github.com/zscaler/n8n-nodes-aiguard\u003e\n- Zscaler AI Guard: \u003chttps://help.zscaler.com/ai-guard\u003e\n- Zscaler Python SDK: \u003chttps://github.com/zscaler/zscaler-sdk-python\u003e\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch from `main`\n3. Test thoroughly against the AI Guard API\n4. Ensure `npm run build`, `npm run lint`, `npm run lint:dist`, and `npm test` pass\n5. Use conventional commit messages (`fix:`, `feat:`, etc.) so releases version correctly\n6. Submit a pull request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzscaler%2Fn8n-nodes-aiguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzscaler%2Fn8n-nodes-aiguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzscaler%2Fn8n-nodes-aiguard/lists"}