Aikido

Loading version...

Port's Aikido integration allows you to model Aikido resources in your software catalog and ingest data into them.

Supported resources RepositoriesIssuesIssue GroupsContainersTeams

Core support

Live eventsSee supported resources

Setup

Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.

Configuration

Port integrations use a YAML mapping block to ingest data from the third-party api into Port.

The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.

Webhook Configuration

To enable real-time data synchronization from Aikido to Port, you must configure webhooks in Aikido following this guide. This setup allows Port to receive immediate notifications whenever relevant changes occur in Aikido. When setting up the webhook, the URL should follow the format:

<base_url>/integration/webhook

IMPORTANT

For security and event authenticity, we strongly recommend setting an HMAC secret in the Aikido dashboard. Once configured, make sure to set the corresponding value in your Port environment using the variable OCEAN__INTEGRATION__CONFIG__WEBHOOK_SECRET . This ensures Port can securely verify incoming webhook events from Aikido.

Default mapping configuration

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)

deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
  - kind: repositories
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"aikidoRepository"'
          identifier: .id | tostring
          title: .name
          properties:
            name: .name
            provider: .provider
            externalRepoId: .external_repo_id
            active: .active
            url: .url
            branch: .branch
            lastScannedAt: .last_scanned_at
  - kind: issues
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"aikidoIssue"'
          identifier: .id | tostring
          title: (.rule // .id) | tostring
          properties:
            status: .status
            severity: .severity
            severityScore: .severity_score
            affectedFile: .affected_file
            attackSurface: .attack_surface
            type: .type
            rule: .rule
            codeRepoId: .code_repo_id
            codeRepoName: .code_repo_name
          relations:
            aikidoRepository: .code_repo_id | tostring

Mapping & selectors per resource

{
    "identifier": "aikidoRepository",
    "title": "Aikido Repository",
    "icon": "Aikido",
    "schema": {
        "properties": {
            "name": {
                "type": "string",
                "title": "Repository Name"
            },
            "provider": {
                "type": "string",
                "title": "Provider",
                "enum": ["github", "gitlab", "gitlab-server", "bitbucket", "azure_devops", "selfscan"]
            },
            "externalRepoId": {
                "type": "string",
                "title": "External Repository ID"
            },
            "active": {
                "type": "boolean",
                "title": "Active"
            },
            "url": {
                "type": "string",
                "title": "Repository URL"
            },
            "branch": {
                "type": "string",
                "title": "Default Branch"
            },
            "lastScannedAt": {
                "type": "number",
                "title": "Last Scanned At"
            }
        },
        "required": ["name", "provider"]
    },
    "relations": {
        "aikidoIssue": {
            "title": "Issues",
            "target": "aikidoIssue",
            "required": false,
            "many": true
        }
    }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: repositories
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"aikidoRepository"'
          identifier: .id | tostring
          title: .name
          properties:
            name: .name
            provider: .provider
            externalRepoId: .external_repo_id
            active: .active
            url: .url
            branch: .branch
            lastScannedAt: .last_scanned_at

{
  "id": 1,
  "name": "Compression service",
  "provider": "github",
  "external_repo_id": "R_kgDOI5RlKA",
  "active": true,
  "url": "https://api.github.com/repos/aikidemo/compression-service",
  "branch": "main",
  "last_scanned_at": 1720083163
}

Below are the supported selectors for this resource. Use them under the selector key in your integration mapping configuration to control which resources are returned from the API.

Selector	Type	Description
exportEnvVariables	array	Environment variable names whose values should be included in lakehouse ingest payloads for DSP processing.
includeInactive	boolean	Whether to include inactive repositories Default: false.

{
  "identifier": "aikidoIssue",
  "title": "Aikido Issue",
  "icon": "Aikido",
  "schema": {
      "properties": {
          "groupId": {
              "type": "number",
              "title": "Group ID"
          },
          "attackSurface": {
              "type": "string",
              "title": "Attack Surface",
              "enum": ["backend", "frontend", "infrastructure", "docker_container",  "cloud"]
          },
          "status": {
              "type": "string",
              "title": "Status",
              "enum": ["open", "closed", "ignored", "snoozed"],
              "enumColors": {
                  "open": "red",
                  "closed": "green",
                  "ignored": "yellow",
                  "snoozed": "blue"
              }
          },
          "severity": {
              "type": "string",
              "title": "Severity",
              "enum": ["critical", "high", "medium", "low"]
          },
          "severityScore": {
              "type": "number",
              "title": "Severity Score"
          },
          "type": {
              "type": "string",
              "title": "Issue Type",
              "enum": ["open_source", "leaked_secret", "cloud", "iac", "sast", "mobile", "surface_monitoring", "malware", "eol", "scm_security", "ai_pentest", "license"]
          },
          "rule": {
              "type": "string",
              "title": "Rule Name"
          },
          "affectedFile": {
              "type": "string",
              "title": "Affected File"
          },
          "codeRepoName": {
              "type": "string",
              "title": "Code Repository Name"
          },
          "codeRepoId": {
              "type": "number",
              "title": "Code Repository ID"
          },
          "closedAt": {
              "type": "number",
              "title": "Closed At"
          }
      },
      "required": ["status", "severity", "type"]
  },
  "relations": {
      "aikidoRepository": {
          "title": "Repository",
          "target": "aikidoRepository",
          "required": false,
          "many": false
      }
  }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: issues
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"aikidoIssue"'
          identifier: .id | tostring
          title: (.rule // .id) | tostring
          properties:
            status: .status
            severity: .severity
            severityScore: .severity_score
            affectedFile: .affected_file
            attackSurface: .attack_surface
            type: .type
            rule: .rule
            codeRepoId: .code_repo_id
            codeRepoName: .code_repo_name
          relations:
            aikidoRepository: .code_repo_id | tostring

{
    "id": 1,
    "group_id": 1,
    "attack_surface": "backend",
    "status": "open",
    "severity": 90,
    "severity_score": "critical",
    "type": "open_source",
    "rule": "SQL injection",
    "rule_id": "aik_cloud_aws_001",
    "affected_package": "minimist",
    "affected_file": "index.php",
    "first_detected_at": 1700489005,
    "code_repo_name": "test-service",
    "code_repo_id": 1,
    "container_repo_id": 1,
    "container_repo_name": "aikido/test-service",
    "sla_days": 5,
    "sla_remediate_by": 1700924603,
    "ignored_at": null,
    "ignored_by": "user",
    "closed_at": null,
    "start_line": 68,
    "end_line": 70,
    "snooze_until": null,
    "cwe_classes": [
      "CWE-89"
    ],
    "installed_version": "4.2.0",
    "patched_versions": [
      "4.2.1",
      "5.0.0"
    ],
    "license": null,
    "programming_language": "PHP"
}

Below are the supported selectors for this resource. Use them under the selector key in your integration mapping configuration to control which resources are returned from the API.

Selector	Type	Description
exportEnvVariables	array	Environment variable names whose values should be included in lakehouse ingest payloads for DSP processing.
filterStatus	string	Filter issues by status. Default: "all".
filterSeverities	array	Filter issues by one or more severities. Multiple values are combined with OR.
filterIssueType	string	Filter issues by type.

{
  "identifier": "aikidoIssueGroup",
  "title": "Aikido Issue Group",
  "icon": "Aikido",
  "schema": {
      "properties": {
          "description": {
              "type": "string",
              "title": "Description"
          },
          "type": {
              "type": "string",
              "title": "Issue Type",
              "enum": ["open_source", "leaked_secret", "cloud", "iac", "sast", "surface_monitoring", "malware", "eol", "scm_security", "ai_pentest", "license"]
          },
          "severity": {
              "type": "string",
              "title": "Severity",
              "enum": ["critical", "high", "medium", "low"]
          },
          "severityScore": {
              "type": "number",
              "title": "Severity Score"
          },
          "groupStatus": {
              "type": "string",
              "title": "Group Status",
              "enum": ["new", "todo", "task_open", "task_closed", "pull_request_open"]
          },
          "timeToFixMinutes": {
              "type": "number",
              "title": "Time To Fix (minutes)"
          },
          "locations": {
              "type": "array",
              "title": "Locations"
          },
          "howToFix": {
              "type": "string",
              "title": "How To Fix"
          },
          "relatedCveIds": {
              "type": "array",
              "title": "Related CVE IDs",
              "items": {
                  "type": "string"
              }
          }
      },
      "required": ["severity", "type", "groupStatus", "severityScore"]
  },
  "relations": {
      "aikidoRepositories": {
          "title": "Repositories",
          "target": "aikidoRepository",
          "required": false,
          "many": true
      },
      "aikidoContainers": {
          "title": "Containers",
          "target": "aikidoContainer",
          "required": false,
          "many": true
      },
      "aikidoTeam": {
          "title": "Team",
          "target": "aikidoTeam",
          "required": false,
          "many": false
      }
  }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: issue_groups
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"aikidoIssueGroup"'
          identifier: .id | tostring
          title: .title
          properties:
            description: .description
            type: .type
            severityScore: .severity_score
            severity: .severity
            groupStatus: .group_status
            timeToFixMinutes: .time_to_fix_minutes
            locations: .locations
            howToFix: .how_to_fix
            relatedCveIds: .related_cve_ids
          relations:
            aikidoRepositories: >-
              [.locations[]? | select(.type == "code_repository") | (.id | tostring)]
            aikidoContainers: >-
              [.locations[]? | select(.type == "container_repository") | (.id | tostring)]
            # Populated only when scopeToTeam is true (uses the __team_id enrichment).
            aikidoTeam: .__team_id | tostring

{
  "id": 26361953,
  "type": "open_source",
  "title": "golang.org/x/crypto",
  "description": "Attacker can trigger DOS-attack",
  "severity_score": 92,
  "severity": "critical",
  "group_status": "new",
  "time_to_fix_minutes": 30,
  "locations": [
    {
      "id": 1841546,
      "name": "test-azure-sync-project",
      "type": "code_repository"
    }
  ],
  "how_to_fix": "In order to fix all of these vulnerabilities, update golang.org/x/crypto to 0.45.0. In order to solve only the critical issues, update to 0.31.0 or upgrade one at a time.",
  "related_cve_ids": [
    "CVE-2024-45337",
    "CVE-2025-22869",
    "CVE-2025-58181",
    "CVE-2025-47914"
  ],
  "__team_id": 1310048,
  "__team_name": "Backend Team"
}

Below are the supported selectors for this resource. Use them under the selector key in your integration mapping configuration to control which resources are returned from the API.

Selector	Type	Description
exportEnvVariables	array	Environment variable names whose values should be included in lakehouse ingest payloads for DSP processing.
scopeToTeam	boolean	Whether to fetch issue groups scoped per active team. When true, each issue group is enriched with __team_id and __team_name fields, which can be used to populate the aikidoTeam relation on the aikidoIssueGroup blueprint. Default: false.

{
  "identifier": "aikidoContainer",
  "title": "Aikido Container",
  "icon": "Aikido",
  "schema": {
      "properties": {
          "provider": {
              "type": "string",
              "title": "Provider"
          },
          "cloudId": {
              "type": "number",
              "title": "Cloud ID"
          },
          "registryId": {
              "type": "number",
              "title": "Registry ID"
          },
          "registryName": {
              "type": "string",
              "title": "Registry Name"
          },
          "tag": {
              "type": "string",
              "title": "Tag"
          },
          "distro": {
              "type": "string",
              "title": "Distro"
          },
          "distroVersion": {
              "type": "string",
              "title": "Distro Version"
          },
          "lastScannedAt": {
              "type": "number",
              "title": "Last Scanned At"
          },
          "lastScannedTag": {
              "type": "string",
              "title": "Last Scanned Tag"
          },
          "lastPushedAt": {
              "type": "number",
              "title": "Last Pushed At"
          },
          "createdAt": {
              "type": "number",
              "title": "Created At"
          },
          "isActive": {
              "type": "boolean",
              "title": "Active"
          }
      },
      "required": ["provider", "tag"]
  },
  "relations": {
      "aikidoRepository": {
          "title": "Repository",
          "target": "aikidoRepository",
          "required": false,
          "many": false
      }
  }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: containers
    selector:
      query: 'true'
      filterStatus: 'active'
    port:
      entity:
        mappings:
          blueprint: '"aikidoContainer"'
          identifier: .id | tostring
          title: .name
          properties:
            provider: .provider
            cloudId: .cloud_id
            registryId: .registry_id
            registryName: .registry_name
            tag: .tag
            distro: .distro
            distroVersion: .distro_version
            lastScannedAt: .last_scanned_at
            lastScannedTag: .last_scanned_tag
            lastPushedAt: .last_pushed_at
            createdAt: .created_at
            isActive: .is_active
          relations:
            aikidoRepository: .linked_code_repo_id | tostring

{
  "id": 1,
  "name": "pied-piper/compression",
  "provider": "aws",
  "cloud_id": null,
  "registry_id": 3,
  "registry_name": "Pied Piper Global Cloud Infrastructure",
  "tag": "prod-*",
  "distro": "debian",
  "distro_version": "12",
  "last_scanned_at": 1720083163,
  "last_scanned_tag": "prod-20250623",
  "linked_code_repo_id": 67,
  "last_pushed_at": 1720083163,
  "created_at": 1720070000,
  "is_active": true
}

Below are the supported selectors for this resource. Use them under the selector key in your integration mapping configuration to control which resources are returned from the API.

Selector	Type	Description
exportEnvVariables	array	Environment variable names whose values should be included in lakehouse ingest payloads for DSP processing.
filterStatus	string	Filter containers by status: all, active, or inactive Default: "active".

{
  "identifier": "aikidoTeam",
  "title": "Aikido Team",
  "icon": "Aikido",
  "schema": {
      "properties": {
          "externalSource": {
              "type": "string",
              "title": "External Source",
              "enum": ["github", "gitlab", "bitbucket"]
          },
          "externalSourceId": {
              "type": "string",
              "title": "External Source ID"
          },
          "responsibilities": {
              "type": "array",
              "title": "Responsibilities"
          },
          "active": {
              "type": "boolean",
              "title": "Active"
          }
      },
      "required": ["active"]
  },
  "relations": {
      "aikidoRepositories": {
          "title": "Repositories",
          "target": "aikidoRepository",
          "required": false,
          "many": true
      },
      "aikidoContainers": {
          "title": "Containers",
          "target": "aikidoContainer",
          "required": false,
          "many": true
      }
  }
}

createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: team
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"aikidoTeam"'
          identifier: .id | tostring
          title: .name
          properties:
            externalSource: .external_source
            externalSourceId: .external_source_id
            responsibilities: .responsibilities
            active: .active
          relations:
            aikidoRepositories: >-
              .responsibilities | map(select(.type == "code_repository") | .id | tostring)
            aikidoContainers: >-
              .responsibilities | map(select(.type == "container_repository") | .id | tostring)

{
  "id": 1310045,
  "name": "test-azure-sync-project Team",
  "external_source": "azure_devops",
  "external_source_id": "f2aeaf29-ca65-4631-8554-a35ac5812617",
  "responsibilities": [
    {
      "id": 1841542,
      "type": "code_repository",
      "included_paths": null,
      "excluded_paths": null
    },
    {
      "id": 1841546,
      "type": "code_repository",
      "included_paths": null,
      "excluded_paths": null
    }
  ],
  "active": true
}

Set up live events

This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.

Note that different events are supported depending on the resource type.

Hosted by Port

Live events base URL

For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.

Call the endpoint with your integration's identifier:

curl -X GET \
  'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
  -H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'

Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

In the response, look for the following fields under spec.appSpec:

{
  "spec": {
    "appSpec": {
      "liveEventsUuid": "abcdefghijk",
      "liveEventsIngestHostname": "ingest.ocean.getport.io"
    }
  }
}

Combine them to build the live events base URL:

https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>

For example, with the values above, the live events base URL is:

https://ingest.ocean.getport.io/live-events/abcdefghijk

This is the same URL configured for the integration.

Self-hosted

BaseUrl & webhook configuration

To enable real-time updates of the data in your software catalog, you need to define the liveEvents.baseUrl parameter.
This parameter should be set to the URL of your Aikido integration instance, which needs to have the option to setup webhooks via HTTP requests/receive HTTP requests, so ensure the network is configured accordingly.

• If Aikido and the integration are in the same cluster/network: Use an internal URL (e.g., a Kubernetes service DNS name).
  For Kubernetes deployments, create a service to expose the integration pod and use the service URL as liveEvents.baseUrl. If both the source system and integration are in the same cluster, an internal ClusterIP service is sufficient.
• If Aikido is external to the integration's network: The integration must be exposed via an ingress, load balancer, or public URL that Aikido can reach.

If liveEvents.baseUrl is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the scheduledResyncInterval parameter has to be set, or a manual resync will need to be triggered through Port's UI.

Debugging local integrations

To test webhooks or live event delivery to your local environment, expose your local pod or service to the internet using ngrok (e.g. ngrok http http://localhost:8000)

Monitoring and sync status

To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.