Skip to main content
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor’s documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
This article explains how to connect Cortex entities to Apiiro. For configuration instructions, see Configuring the integration for Apiiro. For what you can do once entities are connected, see Using the integration for Apiiro.

​
Connecting an entity to Apiiro

Before Cortex can show Apiiro risks on an entity, the entity needs to be connected to an application or repository in Apiiro. Cortex connects entities to Apiiro repositories automatically when their repository paths match. To connect an entity to an application, or to a repository whose path doesn’t match, map it in the entity’s YAML. This page explains both methods and how to confirm that an entity is connected.

​
Importing entities from Apiiro

The Apiiro integration doesn’t import entities into Cortex. It adds security risk data to entities that already exist in your catalog. To add entities to Cortex, see Adding entities.

​
Connecting entities automatically

If an entity has a git repository and no x-cortex-apiiro block, Cortex connects it to any Apiiro repository with the same path. Cortex compares the repository path from the entity’s x-cortex-git block (for example, my-org/my-service) to the repository paths in Apiiro. Keep these rules in mind:
  • Matches are exact. Matching is case-sensitive, and Cortex doesn’t normalize spaces or punctuation. My-Org/My-Service doesn’t match my-org/my-service.
  • Only paths are compared. Cortex doesn’t match on repository URLs, repository IDs, entity names, or Cortex tags.
  • Every match is kept. If more than one Apiiro repository has the same path, Cortex connects the entity to all of them.
  • Applications aren’t matched automatically. To connect an entity to an Apiiro application, map it manually.
Cortex refreshes its list of Apiiro repositories every night at 10 p.m. UTC. A repository you add to Apiiro won’t match any entities until after the next refresh. Cortex matches entities to repositories when it loads their Apiiro data, so you don’t need to take any action after you configure the integration.
Automatic matching requires a git repository on the entity. Entities without an x-cortex-git block only connect to Apiiro through manual mapping.

​
Connecting entities manually

Add an x-cortex-apiiro block to an entity’s YAML to connect it to specific Apiiro repositories or applications. Use manual mapping when:
  • You want to connect an entity to an Apiiro application.
  • The entity’s repository path doesn’t exactly match the path in Apiiro.
  • The entity doesn’t have a git repository in Cortex.
A manual mapping replaces automatic matching for that entity. If you add an x-cortex-apiiro block that lists only applications, Cortex stops matching the entity’s git repository. To keep the repository connected, list it under repositories as well.

​
Mapping an entity in its YAML

  1. In Apiiro, find each repository or application you want to connect to the entity. For a repository, you can use either its ID or its path (e.g. my-org/my-service). For an application, you need its ID.
  2. In Cortex, navigate to the entity’s YAML:
    1. From the main sidebar, expand Catalogs, then select All entities.
    2. Do one of the following:
      • Select the All tab to search and filter across all of your organization’s entities.
      • Select the Mine tab to search and filter only the entities you own.
      • Note that Cortex saves your selection and restores it the next time you open this page.
    3. Select your entity.
    4. From the entity’s left sidebar, select Entity YAML.
    5. In the upper-right corner, click Configure entity.
  3. Add an x-cortex-apiiro block. You can list repositories, applications, or both. Set each entry’s alias to the alias of your Apiiro configuration in Cortex.
  4. Click Save changes.

​
Field reference

You can include repositories, applications, or both. If an entity has neither, Cortex uses automatic matching.
Every entry needs an alias, and every repository entry needs exactly one of repositoryId or repositoryPath. If any entry is missing a required field, Cortex ignores the entire x-cortex-apiiro block without showing an error.

​
How repository and application mappings differ

Both types of mapping show risks in the same places: the Code & security block on the entity’s overview page, and apiiro.risks() in CQL. The difference is which risks Cortex pulls in:
  • Repository mapping - Cortex shows only the risks in that repository.
  • Application mapping - Cortex shows every risk Apiiro associates with that application, which can span multiple repositories.
If an entity has both, Cortex combines the results and removes duplicates, so each risk appears once.
The Code & security block only appears if the entity has at least one risk. If the entity is connected but has no risks, the block doesn’t appear.

​
Using multiple configurations

If you have more than one Apiiro configuration in Cortex (for example, one for each Apiiro instance), one entity can connect to repositories and applications under different aliases. Cortex pulls risks from each configuration, then combines the results and removes duplicates.

​
Verifying the connection

After an entity is connected, check that its Apiiro data appears in Cortex:
  • On the entity’s details page - Risks appear in the Code & security block on the overview, grouped by severity. For the full list, go to Security > Apiiro in the entity’s sidebar.
    The Code & security block only appears if the entity has at least one risk. If the entity is connected but has no risks, the block doesn’t appear.
  • With CQL - Run apiiro != null in the Query builder - US / Query builder - EU to find entities that are connected to Apiiro. Entities that don’t appear in the results aren’t connected.
Last modified on September 30, 2026