Enrich entities using AI

This guide demonstrates how to implement a self-service action in Port that uses AI to enrich entity properties with data from external APIs. This pattern enables you to automatically enhance your entities with intelligent insights from various AI services, making your software catalog more informative and actionable.

In this guide, we will implement a security feature that uses OpenAI's API to analyze security issues and provide insights and possible remediation steps.

Prerequisites

Complete the onboarding process.
Access to the OpenAI API with appropriate permissions.
A blueprint for your entity type in Port.

Set up data model

If you have one of Port's security integrations installed (Snyk, Wiz, or SonarQube), you can simply follow these steps to add the ai_summary property to your existing issue or vulnerability blueprint:

Go to your Builder page.
Search for the blueprint you want to update.
Click on the {...} button in the top right corner, and choose "Edit JSON".

Add this JSON snippet to the properties of the blueprint:

      "ai_summary": {
        "type": "string",
        "title": "AI Analysis",
        "description": "AI-generated analysis and remediation steps",
        "format": "markdown"
      }

Click Save.

However, if you don't have a security integration installed, follow these steps to create a new blueprint with the structure below:

Go to your Builder page.
Click on the + Blueprint button.
Click on the {...} button in the top right corner, and choose "Edit JSON".

Copy and paste the following JSON configuration into the editor.

Security Issue Blueprint (Click to expand)

{
  "identifier": "security_issue",
  "title": "Security Issue",
  "schema": {
    "properties": {
      "rule_name": {
        "type": "string",
        "title": "Rule Name",
        "description": "Name of the security rule or CVE"
      },
      "ai_summary": {
        "type": "string",
        "title": "AI Analysis",
        "description": "AI-generated analysis and remediation steps",
        "format": "markdown"
      }
    }
  }
}

Click Save.

Implementation

Add Port secrets

To add this secret to your portal:

Click on the ... button in the top right corner of your Port application.
Click on Credentials.
Click on the Secrets tab.
Click on + Secret and add the following secret:
- OPEN_AI_API_KEY - Your OpenAI API key

Create a self-service action

Follow these steps to create the self-service action:

Head to the self-service page.
Click on the + New Action button.
Click on the {...} Edit JSON button.

Copy and paste the following JSON configuration into the editor.

Enrich entity with security issue analysis (Click to expand)

{
  "identifier": "enrich_security_issue_with_ai",
  "title": "Enrich entity with security issue analysis using AI",
  "icon": "Codacy",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {},
      "required": [],
      "order": []
    },
    "blueprintIdentifier": "security_issue"
  },
  "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.openai.com/v1/chat/completions",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
      "RUN_ID": "{{ .run.id }}",
      "Content-Type": "application/json",
      "Authorization": "Bearer {{ .secrets.OPEN_AI_API_KEY }}"
    },
    "body": {
      "model": "gpt-3.5-turbo",
      "messages": [
        {
          "role": "system",
          "content": "you are a security expert and should help remediate issues. Lookup for this CVE and provide in markdown few sentences on what is it and how to resolve. Limit to 500 chars. Return in markdown formatting."
        },
        {
          "role": "user",
          "content": " {{ .entity.properties.rule_name }} "
        }
      ]
    }
  }
}

Blueprint identifier

Remember to replace the security_issue identifier with the identifier of your blueprint if you are using any of Port's security integrations. ie snykVulnerability, wizIssue, sonarQubeIssue for Snyk, Wiz, and SonarQube respectively.

Click Save.

Create an automation to update entity

After each execution of the action, we want to update the relevant entity in Port with the AI-generated analysis.

To create the automation:

Head to the automation page.
Click on the + Automation button.

Copy and paste the following JSON configuration into the editor.

Update Entity with AI Analysis (Click to expand)

{
  "identifier": "updateSecurityMarkdown",
  "title": "Update security markdown based on AI analysis",
  "trigger": {
    "type": "automation",
    "event": {
      "type": "RUN_UPDATED",
      "actionIdentifier": "enrich_security_issue_with_ai"
    },
    "condition": {
      "type": "JQ",
      "expressions": [
        ".diff.after.status == \"SUCCESS\""
      ],
      "combinator": "and"
    }
  },
  "invocationMethod": {
    "type": "UPSERT_ENTITY",
    "blueprintIdentifier": "security_issue",
    "mapping": {
      "identifier": "{{ .event.diff.after.entity.identifier }} ",
      "properties": {
        "ai_summary": "{{ .event.diff.after.response.choices[0].message.content }}"
      }
    }
  },
  "publish": true
}

Blueprint identifier

Click Save.

Let's test it!

Head to the self-service page of your portal
Click on the Enrich entity with security issue analysis using AI action
Choose the security issue you want to analyze
Click on Execute
Wait for the AI to analyze the security issue
Verify that the entity in Port has been updated with the AI-generated analysis in the ai_summary field

Prerequisites​

Set up data model​

Implementation​

Add Port secrets​

Create a self-service action​

Create an automation to update entity​

Let's test it!​

Prerequisites

Set up data model

Implementation

Add Port secrets

Create a self-service action

Create an automation to update entity

Let's test it!