Set up Port's n8n custom node

[PeyGis]

User description

Description

The PR contains two guides and one update to docs:

1. Set up Port's n8n custom node located at: docs/guides/all/setup-port-n8n-node.md
2. Remediate security vulnerability with n8n and Port AI: docs/guides/all/remediate-vulnerability-with-n8n-and-port.md
3. Update context lake docs to add how to integrate with external workflows like n8n: docs/ai-interfaces/context-lake.md

Added docs pages

Please also include the path for the added docs

• Quickstart (/)
• Blueprint (/platform-overview/port-components/blueprint)
• ...

Updated docs pages

Please also include the path for the updated docs

• Quickstart (/)
• Blueprint (/platform-overview/port-components/blueprint)
• ...

---

PR Type

Documentation, Enhancement

---

Description

• Add comprehensive guide for using Port as context lake for n8n vulnerability management

• Demonstrate AI-powered vulnerability enrichment with service metadata and ownership context

• Provide n8n workflow template for targeted Slack notifications and automated remediation

• Include context retriever AI agent setup instructions and workflow configuration details

---

Diagram Walkthrough

flowchart LR
  A["Vulnerability Alert"] -->|Webhook| B["n8n Workflow"]
  B -->|Query| C["Port Context Retriever AI"]
  C -->|Service Metadata| D["Enriched Context"]
  D -->|Route| E["Slack Notification"]
  D -->|Route| F["AI Remediation"]
  F -->|Generate Fix| G["Pull Request"]

Loading

File Walkthrough

Relevant files

Documentation

consts.js Register n8n context lake guide in guides section                src/components/guides-section/consts.js Add new guide entry for Port context lake n8n vulnerability management Include guide title, description, tags, logos, and documentation link Integrate into existing guides array with proper formatting +7/-0      port-as-context-lake-for-n8n-vulnerability-management.md Complete guide for Port n8n vulnerability management integration docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md Create comprehensive guide explaining Port as context lake architecture for n8n workflows Document context retriever AI agent setup with JSON schema and configuration Provide complete n8n workflow template with webhook trigger, Port API integration, and AI nodes Include workflow patterns for targeted Slack notifications and AI-powered remediation routing Add prerequisites, testing instructions, and related guides references +547/-0

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Insecure secret handling Description: The guide includes a request body example that posts plaintext Port clientId and clientSecret to obtain an access token, which could encourage insecure handling of long‑lived secrets if copied as-is into workflows or logs. port-as-context-lake-for-n8n-vulnerability-management.md [241-248] Referred Code { "parameters": { "method": "POST", "url": "https://api.port.io/v1/auth/access_token", "sendBody": true, "specifyBody": "json", "jsonBody": "{\n \"clientId\":\"<PORT_CLIENT_ID>\",\n \"clientSecret\": \"<PORT_CLIENT_SECRET>\"\n}", "options": {}
	Sensitive information exposure Description: The n8n workflow uses an OpenAI node with a specific credential name and model identifier and may log AI prompt/response content, which could inadvertently expose vulnerability details or context in logs if not configured to redact; advise secure logging and data minimization. port-as-context-lake-for-n8n-vulnerability-management.md [112-140] Referred Code { "parameters": { "resource": "chat", "model": "o4-mini", "prompt": { "messages": [ { "content": "=You are a cybersecurity assistant. Given the following vulnerability details, summarize the issue, assess impact, and generate a clear remediation plan.\n\nVulnerability:{{ $('Webhook Trigger').item.json.body.vulnerability_id }}\nDescription: {{ $('Webhook Trigger').item.json.body.description }}\nSeverity: {{ $('Webhook Trigger').item.json.body.severity }}\n\nContext:{{$json.result.message}}\n\nOutput format (strict JSON):{\"summary\":\"\",\"impact\": \"\", \"remediation_plan\": \"\", \"is_fixable\": boolean true or false}" } ] }, "options": {}, "requestOptions": {} }, "name": "OpenAI Remediation Plan", "type": "n8n-nodes-base.openAi", "typeVersion": 1, "position": [ 16, 112 ], ... (clipped 8 lines)
	Data exfiltration risk Description: The workflow posts to an AI agent endpoint with provider/model fields (including "gpt-5") and passes vulnerability details; if transmitted without strict region-specific endpoints or TLS verification settings in n8n, data could be sent to unintended regions—ensure HTTPS, correct regional endpoints, and certificate verification. port-as-context-lake-for-n8n-vulnerability-management.md [292-306] Referred Code ] }, "sendBody": true, "specifyBody": "json", "jsonBody": "={\n \"prompt\": \"You are an assistant that provides contextual enrichment for vulnerabilities using the Port catalog as a knowledge base. A new security vulnerability has been detected.\\n\\nVulnerability Details:\\n- Identifier:{{ $('Webhook Trigger').item.json.body.vulnerability_id }}\\n- Description:{{ $('Webhook Trigger').item.json.body.description }}\\n-Severity:{{ $('Webhook Trigger').item.json.body.severity }}\\n\\nUsing the Port catalog (which stores data about services, components, environments, owners, and relationships), return relevant contextual information that will help downstream AI agents or security teams understand how this vulnerability relates to other entities. Specifically, retrieve:\\n\\n1. The affected service(s) or components linked to this vulnerability\\n2. Ownership or responsible team(s)\\n3. Related environments or deployment targets\\n4. Dependencies or linked entities in the Port catalog (for example, linked repositories, cloud resources, or microservices)\\n5. Any additional metadata that can help prioritize or triage this vulnerability.\\n\\nFormat the response as structured JSON with the following keys: `identifier`, `title`, `related_services`, `owners`, `environments`, `dependencies`, and `notes`.\",\n \"labels\": {\n \"source\": \"n8n-workflow\",\n \"use_case\": \"vulnerability-context-enrichment\"\n },\n \"provider\": \"openai\",\n \"model\": \"gpt-5\"\n}", "options": {} }, "name": "Get Context From Port AI", "type": "n8n-nodes-base.httpRequest", "typeVersion": 3, "position": [ -688, 112 ], "id": "f08cf680-ae0b-43f0-90b8-3ff6763c5071"
	Sensitive information exposure Description: Slack message composition may include detailed vulnerability data and AI outputs sent to a default channel placeholder; if misconfigured this could leak sensitive information to broad audiences—recommend using restricted channels and masking sensitive fields. port-as-context-lake-for-n8n-vulnerability-management.md [221-239] Referred Code "channel": "<DEFAULT_SLACK_CHANNEL>", "text": "={{ \n`🚨 *Vulnerability Alert*\n\n*ID:* ${$('Webhook Trigger').item.json.body.vulnerability_id}\n*Severity:* ${$('Webhook Trigger').item.json.body.severity}\n*Summary:* ${$node[\"OpenAI Remediation Plan\"].json[\"message\"][\"content\"].parseJson().summary}\n*Impact:* ${$node[\"OpenAI Remediation Plan\"].json[\"message\"][\"content\"].parseJson().impact}\n*Remediation Plan:* ${$node[\"OpenAI Remediation Plan\"].json[\"message\"][\"content\"].parseJson().remediation_plan}\n\n_Workflow: AI-Assisted Remediation_`\n}}\n", "otherOptions": {}, "attachments": [] }, "name": "Send Slack Message", "type": "n8n-nodes-base.slack", "typeVersion": 1, "position": [ 912, 128 ], "id": "39e20367-b69c-456b-b7dc-79d0bc5f80e1", "credentials": { "slackApi": { "id": "PcHkxZHMrun5N8Tk", "name": "Slack account" } }
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Secrets exposure: The guide embeds credentials placeholders and constructs that could lead to logging or sending tokens/IDs in requests or messages (e.g., bearer tokens, clientId/clientSecret, AI outputs) without explicit guidance to avoid logging sensitive data. Referred Code { "parameters": { "method": "POST", "url": "https://api.port.io/v1/auth/access_token", "sendBody": true, "specifyBody": "json", "jsonBody": "{\n \"clientId\":\"<PORT_CLIENT_ID>\",\n \"clientSecret\": \"<PORT_CLIENT_SECRET>\"\n}", "options": {} }, "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.3, "position": [ -944, 112 ], "id": "bd4db720-50f7-4098-b4c7-84a5a30faf38", "name": "Get Port Access Token", "retryOnFail": true, "maxTries": 2 }, { ... (clipped 38 lines) Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Missing auditing: The added n8n workflow and guidance do not include steps to log critical actions (e.g., context retrieval, remediation triggering, Slack notifications) with user ID, timestamp, action, and outcome. Referred Code <details> <summary><b>n8n Workflow Template (Click to expand)</b></summary> ```json showLineNumbers { "name": "AI-Assisted Vulnerability Remediation", "nodes": [ { "parameters": { "httpMethod": "POST", "path": "security/vulnerability_detected", "options": {} }, "name": "Webhook Trigger", "type": "n8n-nodes-base.webhook", "typeVersion": 1, "position": [ -1200, 112 ], "webhookDescription": "Triggered when a new vulnerability is detected", ... (clipped 225 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Limited errors: The workflow includes an error trigger to Slack but lacks explicit handling for edge cases (e.g., missing webhook fields, failed token retrieval, AI invocation failures) and does not provide actionable context beyond a generic error message. Referred Code { "parameters": { "channel": "#security-updates", "text": "=⚠️ *AI Remediation Workflow Error*\nNode: {{$node.name}}\nError: {{$error.message}}", "otherOptions": {}, "attachments": [] }, "name": "Error Alert Slack", "type": "n8n-nodes-base.slack", "typeVersion": 1, "position": [ -896, 352 ], "id": "3ce14f5b-6929-4aa0-acc0-2e062ee798a7", "credentials": { "slackApi": { "id": "PcHkxZHMrun5N8Tk", "name": "Slack account" } } ... (clipped 12 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Sensitive errors: The Slack error message template includes the node name and raw error message which may expose internal implementation details to a broad Slack channel. Referred Code "parameters": { "channel": "#security-updates", "text": "=⚠️ *AI Remediation Workflow Error*\nNode: {{$node.name}}\nError: {{$error.message}}", "otherOptions": {}, "attachments": [] }, "name": "Error Alert Slack", "type": "n8n-nodes-base.slack", "typeVersion": 1, "position": [ -896, 352 ], "id": "3ce14f5b-6929-4aa0-acc0-2e062ee798a7", "credentials": { "slackApi": { "id": "PcHkxZHMrun5N8Tk", "name": "Slack account" } } Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Input validation: The webhook-driven workflow consumes external payload fields and interpolates them into prompts and messages without documented validation or sanitization steps, which may risk injection or malformed data handling. Referred Code { "content": "=You are a cybersecurity assistant. Given the following vulnerability details, summarize the issue, assess impact, and generate a clear remediation plan.\n\nVulnerability:{{ $('Webhook Trigger').item.json.body.vulnerability_id }}\nDescription: {{ $('Webhook Trigger').item.json.body.description }}\nSeverity: {{ $('Webhook Trigger').item.json.body.severity }}\n\nContext:{{$json.result.message}}\n\nOutput format (strict JSON):{\"summary\":\"\",\"impact\": \"\", \"remediation_plan\": \"\", \"is_fixable\": boolean true or false}" } ] }, "options": {}, Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Simplify the guide's implementation The guide should be changed to walk users through building the n8n workflow step-by-step via its UI, instead of providing a large, opaque JSON file for import. This would make the guide more educational, easier to follow, and less prone to breaking from tool updates. Examples: docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md [82-457] ### Import the n8n workflow template 1. Open your n8n instance 2. Click on **Workflows** → **Import from File** or **Import from URL** 3. Copy the workflow JSON from the template below <details> <summary><b>n8n Workflow Template (Click to expand)</b></summary> ```json showLineNumbers ... (clipped 366 lines) Solution Walkthrough: Before: # Set up the n8n workflow ### Import the n8n workflow template 1. Open your n8n instance 2. Click on Workflows → Import from File or Import from URL 3. Copy the workflow JSON from the template below <details> <summary><b>n8n Workflow Template (Click to expand)</b></summary> ```json { "name": "AI-Assisted Vulnerability Remediation", "nodes": [ ... ], // Large opaque JSON blob "connections": { ... }, ... } ``` </details> 4. After importing, configure the credentials... After: # Set up the n8n workflow Let's build the workflow step-by-step in the n8n UI. ### Step 1: Create a Webhook Trigger 1. In n8n, add a new "Webhook" node. 2. Set the HTTP Method to `POST`. 3. Set the path to `security/vulnerability_detected`. ### Step 2: Get Port Access Token 1. Add an "HTTP Request" node. 2. Configure it to `POST` to `https://api.port.io/v1/auth/access_token`. 3. Set the body with your `clientId` and `clientSecret`. ### Step 3: Get Context From Port AI ... (continue for each node in the workflow) ### Final Workflow Your final workflow should look like this: [Image of the final n8n workflow graph] Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies that providing a monolithic JSON for the n8n workflow is not user-friendly or educational, and proposes a step-by-step guide which would significantly improve the guide's quality and maintainability.	High
Possible issue	Use a placeholder for API endpoint Correct the hardcoded URL in the "Trigger Claude Code" node to be consistent with other API endpoints in the n8n workflow. docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md [311] -"url": "https://api.getport.io/v1/actions/run_claude_code_demo/runs", +"url": "https://api.port.io/v1/actions/run_claude_code_demo/runs", Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies an inconsistent API endpoint URL compared to other calls in the same file, which could cause confusion or errors for users following the guide.	Medium
	Correct the documented API endpoint Update the documented EU API endpoint from https://api.getport.io to https://api.port.io to match the URL used in most of the n8n workflow's API calls. docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md [480-481] - US: `https://api.us.port.io` -- EU: `https://api.getport.io` +- EU: `https://api.port.io` Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that the documented EU API endpoint is inconsistent with the endpoints used in most of the workflow's API calls, which could confuse users.	Medium
Organization best practice	Add descriptive image alt text Add descriptive alt text to images for accessibility and clarity. docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md [15] -<img src='/img/guides/port-context-lake-n8n-workflow.png' border="1px" width="100%" /> +<img src='/img/guides/port-context-lake-n8n-workflow.png' width='100%' border='1px' alt='n8n workflow using Port as a context lake for vulnerability management' /> Apply / Chat Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Pattern 13: Format images with width, border, full path, and alt text.	Low
	✅ Standardize details summary text Suggestion Impact: The summary was changed from "Context Retriever Agent (Click to expand)" to "Context retriever agent (click to expand)" in the details block, matching the suggested sentence case and phrasing. code diff: - <details> - <summary><b>Context Retriever Agent (Click to expand)</b></summary> - Use sentence case and the exact "(click to expand)" phrasing for collapsible details summaries for consistency. docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md [52] <details> -<summary><b>Context Retriever Agent (Click to expand)</b></summary> +<summary><b>Context retriever agent (click to expand)</b></summary> ... </details> [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 4 __ Why: Relevant best practice - Pattern 1: Standardize collapsible details with bold titles and "(click to expand)" in the summary.	Low
	✅ Add showLineNumbers to code block Suggestion Impact: The committed changes added "showLineNumbers" to multiple JSON code fences, including the sample payload block that the suggestion referenced. code diff: - ```json showLineNumbers - { - "identifier": "context_retriever_agent", - "title": "Context Retriever Agent", - "icon": "Details", - "team": [], - "properties": { - "description": "AI agent that provides contextual enrichment for any entity or event using the Port catalog as a knowledge base", - "status": "active", - "prompt": "You are an assistant that provides **contextual enrichment** for any entity or event using the **Port catalog** as a knowledge base. Your goal is to retrieve relevant context that helps downstream systems, agents, or security teams understand how a given entity fits within the broader ecosystem.\n\nYou will receive an input describing an **entity or event**.\nAnalyze the input and use the Port catalog to return structured contextual information.\n\n**Example inputs include:**\n\n* A detected security vulnerability\n* An active incident or outage\n* A new deployment or release event\n* A system health anomaly\n\n---\n\n### **For each input, provide the following:**\n\n1. Affected service(s) or component(s)\n2. Ownership or responsible team(s)\n3. Related environments or deployment targets\n4. Dependencies or linked entities in the Port catalog (e.g., repositories, cloud resources, deployments, last N pull requests, or microservices)\n5. Any additional metadata or relationships that provide useful operational context\n\n---\n\n### **Output Format**\n\nReturn the result as **structured JSON** with the following keys:\n\n`identifier`, `title`, `related_services`, `owners`, `environments`, `dependencies`, and `notes`.\n\n**Example output:**\n\n```json\n{\n \"identifier\": \"INC-1023\",\n \"title\": \"Database connection timeout in payments service\",\n \"related_services\": [\"payments-api\", \"orders-api\"],\n \"owners\": [\"payments-team\"],\n \"environments\": [\"production\"],\n \"dependencies\": [\"postgres-cluster-prod\", \"redis-cache\"],\n \"notes\": \"The issue affects all payment operations in production. Linked to previous incident INC-1009.\"\n}\n```\n\nIf a field cannot be determined, return it as an empty string or an empty list.", - "execution_mode": "Automatic", - "tools": [ - "^(list|get|search|track|describe)_.*" - ] - }, - "relations": {} - } - ``` Add showLineNumbers to multi-line code blocks to improve readability and copy experience. docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md [521-527] -```json +```json showLineNumbers { "vulnerability_id": "CVE-2024-12345", "description": "SQL injection vulnerability in authentication service", "severity": "high" } `[Suggestion processed]` <details><summary>Suggestion importance[1-10]: 4</summary> __ Why: Relevant best practice - Pattern 11: Add queryString to Tabs components and avoid markdown headers inside tabs; also Pattern 4/14: specify language and showLineNumbers on all code fences. </details></details></td><td align=center>Low </td></tr><tr><td> <details><summary>Use full-path new-tab internal link<!-- not_implemented --></summary> ___ **If you want the link to open in a new tab, prefix with https://docs.port.io; <br>otherwise keep the full path as-is consistently across the doc.** [docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md [28]](https://github.com/port-labs/port-docs/pull/3000/files#diff-c73a2bf010dd7b67a01325b71b90acfc693bf800b1d36904f851d27cc21619f8R28-R28) ```diff -- Completed the [onboarding process](/getting-started/overview) +- Completed the [onboarding process](https://docs.port.io/getting-started/overview) Apply / Chat Suggestion importance[1-10]: 4 __ Why: Relevant best practice - Pattern 12 and 21: Use full paths for internal links and use https://docs.port.io to open internal links in a new tab when desired.	Low
	General	Use CSS for image border Replace the obsolete border attribute on the tag with the CSS style attribute for better HTML5 compliance and consistent rendering. docs/guides/all/port-as-context-lake-for-n8n-vulnerability-management.md [15] -<img src='/img/guides/port-context-lake-n8n-workflow.png' border="1px" width="100%" /> +<img src='/img/guides/port-context-lake-n8n-workflow.png' style="border: 1px solid #ccc;" width="100%" /> Apply / Chat Suggestion importance[1-10]: 3 __ Why: The suggestion correctly identifies an obsolete HTML attribute and proposes a modern CSS-based alternative, which is a good practice for maintainability and browser compatibility.	Low
Update

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-3000.d2ngvl90zqbob8.amplifyapp.com

[Matanga1-2]

small formatting comments

[Matanga1-2]

I would add something like "consider creating a service account [link] for each workflow/agent"

[Matanga1-2]

@PeyGis do we control the icon of the node? if we do, can we collaborate with Nathan to have it include the Port logo?

[PeyGis]

on this, Nathan commented here:

The Port search result does not use the Port.io icon (this is a known bug when adding via /custom in n8n, it will fix itself when deployed as an npm package)