Cortex is the AI-powered internal developer portal (IDP) that helps engineering teams ship reliable, secure, and efficient software, faster. It uses AI to make sense of your engineering data, figure out the next unlock for your team, and solve it — all in one place.

Get started with Cortex

Cortex video overview

See an overview of Cortex below:

Accelerate the path to Engineering Excellence

We believe the foundation for Engineering Excellence starts with clear ownership and accountability. With ownership in place, drive complete visibility through the catalogs, a culture of continuous improvement using and , and consistent developer experience through self-service .

Learn how organizations drive Engineering Excellence with Cortex:

The Cortex YAML linter validates your cortex.yaml files for both general YAML syntax and Cortex-specific schema requirements, helping prevent ingestion of invalid or incomplete data into the platform.

This page references the built-in tool in the Cortex UI under Tools > YAML Linter. Note that there is also a linter tool built in to the Cortex GitHub app, which runs checks on pull requests when you use GitHub in a .

Using the YAML linter

In this section, learn how to add each of the built-in entity types and dependencies, and how to create a custom entity type and add custom entities:

Eng Intelligence Dashboards provide engineering leaders and teams with real-time visualizations into key metrics, velocity and productivity trends, incident and quality insights, and historical organzation-wide rollups. Dashboards are natively integrated with your Cortex catalog, Scorecards, and Initiatives, allowing you to move from insight to action.

See the documentation linked below to learn more about each dashboard:

• : Visualize the four key DORA metrics: Cycle time, deployment frequency, change failure rate, and MTTR.

• : Monitor version control metrics such as PR cycle time, PR size, and PR success rate, giving insight into your process efficiency and areas to target for improvement.

Archiving an entity allows you to remove it from active use while preserving its history and context.

You can configure Cortex to automatically archive entities when they are no longer detected in your integrations or when their corresponding YAML files are deleted. We recommend enabling this feature to keep your data up-to-date without manual effort. Learn more in Auto archiving entities.

It's also possible to manually archive entities in the Cortex UI or via the Cortex API, as described below.

How to archive and unarchive entities

To archive entities, your user or API key must have the Archive entities permission. To unarchive entities, your user or API key must have the Configure entities permission.

How archived entities are handled in Cortex

Archived entities are not included in the following Cortex features:

• and

• features, including CQL reports and query builder

The "All entities" and Catalogs pages

By default, archived entities do not appear in the lists on "All entities" or in catalogs, but you can choose to include archived entities in your view.

To include archived entities:

1. Click Display at the top of the list.

2. Toggle on the setting for Show archived.

Note that this setting is not persistent when you navigate away from the page.

An entity details page

On an , if a related dependency, child entity, or parent entity has been archived, it will not be displayed under Relationships in the entity's sidebar.

If the entity itself has been archived, you will see an "Archived" flag appear next to its name:

Entity configuration

While configuring an entity, you cannot add an archived team as an owner. You cannot add archived entities as dependencies or as parent or child entities.

The discovered entities list

Cortex will tag detected changes to signify whether an entity or repository has been archived. Learn more in .

The Cortex Terraform Provider acts as a bridge between Terraform and the Cortex platform, allowing you to manage and provision Cortex resources (such as Scorecards, integrations, and entities) using Terraform’s infrastructure-as-code approach. The provider is a wrapper around the public Cortex API and is maintained by the Cortex team, with shared ownership and ongoing support for customers who use it.

Managing the catalog as code

Many Cortex customers manage their entire service catalog and engineering standards as code using the Cortex Terraform Provider.

Expand the tiles below for examples on how to handle different use cases with this approach.

Install the Terraform Provider for Cortex

For installation instructions, see the .

Examples

See .

Humanitec offers products to build on top of your Internal Developer Portal (IDP) for containerized workloads.

Integrating Humanitec with Cortex allows you to run a Humanitec pipeline directly from Cortex.

How to integrate Humanitec with Cortex

Prerequisites

Before getting started:

• You should have an app with a working pipeline configured in Humanitec.

• Create a service user in Humanitec, and create an for the service user.

Step 1: Create a Workflow in Cortex

1. Follow the instructions to and .

2. Add an HTTP request block to your Workflow. Configure the block:

   • Block name: Enter a descriptive name for the block.

   • Slug: Enter a unique identifier for the block.

Alternatively, you can also use an Async HTTP request block in your Workflow, using the to call back to Cortex.

Step 2: Run the Workflow

• At the top of your Workflow in Cortex, click Run.

In your Humanitec workspace under your app's pipelines, you will see the run listed under the Runs tab:

Example using Cortex with AWS, Humanitec, and Terraform

See the video below where a member of the Humanitec team walks through advanced end-to-end setup on AWS using Cortex, Humanitec as the orchestrator, and Terraform modules deployed via ECS runners. The video demonstrates detecting a policy violation and remediating it.

Rule filters allow you to apply a Scorecard rule only to specific entities. It's helpful to use a rule filter when a rule doesn’t apply to every entity or every group.

You can apply a filter in the Cortex UI while building out your Scorecard rules, or you can write a custom CQL query to filter your rule.

How to set up a Scorecard rule filter

1. When setting up a rule for a Scorecard, click and expand Restrict rule to specific groups.

2. Select the relevant groups to include or exclude.

   • Or, if you prefer to write a CQL query, click Switch to CQL under the group fields.

3. Click Save rule.

See the for instructions on the overall process of creating a Scorecard.

You can also edit an existing Scorecard to add a filter to a rule.

Example Scorecard rule filter

For example, let's say that entities in the "billing" group don't need to have SLOs set up properly.

• In the rule "Has SLOs set up," apply a filter to exclude the "billing" group:

• After saving the rule with the excluded group, view the Scorecard. Any entities in the "billing" group will not be scored against the "Has SLOs set up" rule. The rule will not appear as a passing or a failing rule; it will not be included at all.

View the filter on the Scorecard home page

Once a rule filter has been applied, you can still see it on a Scorecard’s home page. Navigate to the Rules tab and expand the rule to confirm it has been exempted.

Cortex’s On-call Assistant leverages the to automatically surface the most vital information about entity health and metadata when an incident is triggered. On-call Assistant notifies the user(s) responsible for an incident via Slack, including information about the affected entity, recent deployments, ownership, and links to get more details, including dependencies, runbooks, and logs.

On-call Assistant helps users respond to incidents in real time, simplifying the incident response process and helping to reduce MTTR. It can also drive adoption and engagement through links to the catalogs and Scorecards.

How On-call Assistant works

Groups are a tagging system that can be used to group a set of together, enabling a variety of use cases including:

• Tagging

  • Use groups to segment entities.

  • For example, you could segment by tiers (tier-0 to indicate high priority), type (backend, frontend, library, API), or language (Python, Java).

Overview

Okta is an identity and access management (IAM) platform. Integrate Cortex with Okta to drive insights into authentication and ownership.

After configuring the integration, you can set Okta teams and team members as owners of entities.

For information on configuring Okta SSO or Okta SCIM for logging in to Cortex, see the Okta SSO documentation and Okta SCIM documentation.

How to configure Okta with Cortex

Prerequisites

Before getting started:

• An Okta administrator, with at least the permissions, must .

  • Grant the following scopes for the API token:

    • okta.groups.read

Configure the integration in Cortex

1. In Cortex, navigate to the :

   • Click Integrations from the main nav. Search for and select Okta.

2. Click Add configuration.

3. Configure the Okta integration form:

How to connect Cortex entities to Okta

Import teams from Okta

See the for instructions on importing entities.

Team data syncs from Okta daily at 3 p.m. UTC.

Editing the entity descriptor

The group name is case-sensitive and should be exactly the same as in Okta.

Using the Okta integration

Scorecards and CQL

With the Okta integration, you can create Scorecard rules and write CQL queries based on Okta teams.

See more examples in the in Cortex.

View integration logs

Background sync

Cortex conducts an ownership sync for Okta teams every day at 3 p.m. UTC.

Troubleshooting and FAQ

I've added an API token but the login is still using Google.

To set up Okta for SSO, use the .

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

Grafana is an open-source observability platform that provides monitoring and visual analytics for application performance. Use Grafana to visualize your data, from bar charts and histograms to pie charts and geomaps.

Integrating Grafana with Cortex allows you to:

• View Grafana charts on entity pages in Cortex

• Create Scorecards that include rules related to Grafana dashboards

How to configure Grafana with Cortex

Prerequisites

Before getting started:

• Your Grafana dashboard must have .

• Your OR if you are on a instance, then Cortex and Grafana must be accessible within the same private network (such as a VPN).

  • You will need the public embed link provided in the iframe snippet.

Embed the chart in an entity's YAML file

Define the public embed link in the for each entity where you want to embed a chart.

1. For the entity where you want to embed a chart, open its YAML file.

   • You can do this locally if following a approach, or you can edit a YAML file directly in the Cortex UI on the .

2. Add the x-cortex-dashboards block. Include the type (grafana) and the url

Repeat the steps above for each entity you want to add a Grafana chart to.

Using the Grafana integration

Viewing Grafana charts on an entity

Once you've defined the chart in an entity's YAML, you can view the graphs from an .

In an entity's sidebar, click Dashboard. All charts defined in the entity descriptor will be embedded on this page.

Scorecards and CQL

With the Grafana integration, you can create Scorecard rules and write CQL queries based on Grafana charts.

See more examples in the in Cortex.

View integration logs

Background sync

Grafana charts are updated in real time.

FAQs and troubleshooting

I've correctly added the embed URL, but the graph is showing an error or a blank screen.

You may need to in your Grafana instance.

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

Overview

Coralogix is an observability and security platform. Integrate Cortex with Coralogix to drive insights into alerts.

After setting up the integration, relevant alerts from Coralogix will appear in your entity pages. While viewing an entity, click Integrations > Coralogix in its sidebar to view the list of alerts.

How to configure Coralogix with Cortex

Prerequisites

Before getting started, generate a .

Step 1: Configure the integration in Cortex

1. In Cortex, navigate to the

   • Click Integrations from the main nav. Search for and select Coralogix.

2. Click Add configuration.

3. Configure the Coralogix integration form:

How to connect Cortex entities to Coralogix

Discovery

By default, Cortex will use the entity name or (e.g. my-service) as the "best guess" for the Coralogix alert application name. For example, if your entity name is "My Service" and your Cortex tag is “my-service”, then the corresponding application name in Coralogix should be “My Service” or "my-service".

If your Coralogix application names don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

Editing the entity descriptor

Coralogix alerts can be listed in the Catalog under the Coralogix section. We support application names in the YAML for pulling Coralogix alerts.

Using the Coralogix integration

Scorecards and CQL

With the Coralogix integration, you can create Scorecard rules and write CQL queries based on Coralogix alerts.

See more examples in the in Cortex.

View integration logs

Overview

IBM Instana Observability is a tool used for monitoring and performance management. Integrate Instana with Cortex allows you to pull in services from Instana.

How to configure Instana with Cortex

Prerequisite

Before getting started, .

Configure the integration in Cortex

1. In Cortex, navigate to the :

   1. Click Integrations from the main nav. Search for and select Instana.

2. Click Add configuration.

3. Configure the Instana integration form:

How to connect Cortex entities to Instana

Import services from Instana

Cortex automatically syncs from Instana APM at 7 a.m. UTC.

See the for instructions on importing entities.

Import Instana services from Discovery audit

Cortex will pull recent changes from Instana into the . Here, you can find new entities in Instana that have not been imported into the catalog.

View integration logs

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

JQ is a lightweight, flexible command-line JSON processor that allows users to do arbitrary JSON manipulations.

Cortex leverages JQ within CQL to enable complex queries, including queries on YAML files. For instance:

The above query would cycle through the foo object and retrieve the length of all .property components. This type of query is often used on Kubernetes resources.

JQ and datatypes

JQ can provide additional flexibility around data types. For instance, let's say you have a string associated with a numerical value in your Custom Data.

If you wanted to query on the line value as a number rather than string, the following JQ functionality could be used within CQL:

This would result in the respective entity passing this CQL check.

JQ examples

The following examples demonstrate ways you could use JQ in Cortex:

Use JQ to implement conditional logic for selecting file paths dynamically

This checks if custom git data exists, uses the custom dockerfile path if present, or falls back to the default "Dockerfile" path.

Accessing properties with special characters

Use bracket notation to access JSON properties containing dots, slashes, or other special characters:

Handling null values

Prevent errors by checking for null values before accessing properties:

For Scorecard rules, you can use a similar approach:

Wildcard pattern matching

Find packages containing specific strings using the matches() function:

Finding team members by role

Filter team members by role using JQ:

Handling complex YAML structures

When working with complex YAML files like GitLab CI configurations:

Extract the scheme of an AWS load balancer for resource metadata

Or, for nested metadata:

Extracting version from pom.xml file

This query extracts the version number from a Maven pom.xml file. You might use this to automate dependency version checks:

Display a parent entity name in a CQL report

This query would allow you to display a parent entity name value, rather than an array, in a CQL report:

You may have over a hundred repositories in GitHub, and eventually, you will likely import all of them into Cortex. This much information can make it difficult to know at a glance that all repositories are accounted for and all new projects are being imported into and tracked within Cortex.

The discovered entities list (formerly known as the discovery audit) guarantees confidence in your catalogs by listing all changes that Cortex has detected. Cortex compares everything that exists within the system to what it discovers within your git tool, APM tool, Kubernetes cluster, and other crucial integrations, giving you insight into changes happening across your environments.

View the discovered entities

You can view discovered entities under Catalogs > All entities in the Discovered entities tab.

On this page, see a list of recent changes in your environment that aren't yet reflected in Cortex, including newly created repositories, services, and resources discovered from your integrations.

Filter the discovered entities list

The first time you view the discovered entities list, there may be a lot to review. To narrow the scope of your list and start with changes that are the highest priority for you, search or filter the list by integration or entity type.

• To search, enter text into the search bar in the upper right corner of the list.

• To filter, click Filter in the upper right corner of the list. Select your filtering criteria, then click Apply.

Importing and removing entities

Cortex will tag detected changes to signify whether an entity or repository has been discovered, archived, or deleted.

You can import, delete, or ignore the entities listed in Discovery audit.

Import discovered entities

If Cortex detects a new service or resource, you can import it directly from this page:

1. Click + in the row containing the new entity:
2. Configure the entity details.

   • For detailed instructions on creating a new entity, see the relevant docs page for the entity type: , , .

Delete discovered entities

If Cortex no longer detects a given entity, you also have the ability to delete that entity or repository directly from this page:

1. Click the trash can icon in the row containing the entity:\
2. In the confirmation window, click Delete.

   • The confirmation window gives you the opportunity to review all potentially impacted services before deleting, so you don’t unintentionally remove something from Cortex.

Ignore discovered entities

If an event appears within the discovered entities list, but is irrelevant — for example, a test project that doesn’t need to be imported into Cortex — you can ignore it:

• Click the hide icon in the row containing the entity:\

The entity will now appear in the Ignored tab. The ignore action is persistent, so the event won’t appear again within the discovered list.

From the ignored list, you can move the entity back to the Discovered tab by clicking the eye icon.

Troubleshooting and FAQ

Why do I not see all of my services from my APM provider in the discovered entities list?

Cortex supports a subset of integrations within the discovered entities list:

• Datadog

• ECS

• Version control (Azure DevOps, Bitbucket, GitHub, GitLab)

• Instana

is an open source automation server which enables developers to build, test, and deploy software.

Integrating Jenkins with Cortex allows you to:

• Send information about Jenkins deploys into Cortex

  • This data appears on .

• Use

Overview

is a cloud-based observability platform that provides log management and analytics. Integrate Sumo Logic with Cortex to drive insights into service-level objectives (SLOs).

How to configure Sumo Logic with Cortex

Overview

is a Human Resources Information System (HRIS) solution that allows you to define organizational membership. Integrate Cortex with BambooHR to automatically sync team memberships, giving you insight into entity ownership.

How to configure BambooHR with Cortex

Getting your data into Cortex is the foundation for data-driven decision making and improved accountability across your teams.

By connecting your services, repositories, teams, infrastructure, and more, Cortex can provide a complete, up-to-date view of your ecosystem. This powers the ability to track ownership of entities, enforce production readiness and other standards via , standardize common developer for entities, and more. It also ensures your developers can find what they need, understand how everything fits together, and make better decisions at every stage of the development lifecycle.

How Cortex handles data modeling

Some internal developer portals start with too much rigidity or too little guidance. A rigid platform prevents you from correctly modeling relationships between key entities in your environment. An overly modular approach requires you to rebuild business logic for each use case, resulting in the same fractured experience you intended to solve for.

is continuous integration and continuous delivery platform that can be used to implement DevOps best practices.

Integrating CircleCI with Cortex allows you to:

• in Cortex

• Create that track progress and drive alignment on projects involving your CircleCI data

Use Scorecards to establish best practices, track migration, promote accountability among teams, enforce standardization across entities, or define maturity standards.

Azure Resources provides on-demand cloud computing platforms and APIs. Cortex uses the Azure Resource API to pull in resource details and import entities such as SQL servers, virtual machines, virtual networks, load balancers, and others.

Integrating Azure Resources with Cortex allows you to:

• Automatically import entities and track ownership of entities

• Create Scorecards to drive alignment and track progress on projects involving resources from Azure

How to configure Azure Resources with Cortex

Prerequisites

Before getting started, you will need the following information. These can be found in the Enterprise applications section of Azure:

• Azure tenant ID

• Azure client ID and

• Azure subscription ID

  • Ensure that the service principal for the subscription ID has a .

Configure the integration in Cortex

1. In Cortex, navigate to the .

   • Click Integrations from the main nav. Search for and select Azure Resources.

2. Click Add configuration.

3. Configure the Azure Resources integration form:

After saving your configuration, you are redirected to the integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Azure Resources was configured properly.

How to connect Cortex Entities to Azure Resources

Enable automatic discovery of Azure Resource entities

You can configure automatic import from Azure:

1. In Cortex, navigate to the .

2. Next to Auto import from AWS, Azure, and/or Google Cloud, click the toggle to enable the import.\

Discover ownership for Azure Resources

Cortex can automatically discover ownership for your Azure resources. To configure this:

• Make sure that your Azure resources have a tag matching the x-cortex-tag of the corresponding Cortex team

• Enable the “Sync ownership from Azure” toggle in the in Cortex.

  • By default, Cortex looks for the owner tag. You can also customize the tag key name on the Settings page.

Cortex syncs ownership from Azure Resources every day at 6 a.m. UTC.

Define a dependency

Cortex automatically discovers dependencies between your services and resources by scanning for resources with specific Azure Resources tags. By default, a service will have dependencies on any Cortex resource that has a corresponding Azure Resources resource with Azure Resources tag key = "service" and tag value = the service's Cortex tag.

On the , you can customize the tag key names for dependencies.

For more information on defining dependencies, please see the .

Import entities from Azure Resources

See the for instructions on importing entities.

Editing the entity descriptor

You can associate a Cortex entity with one or more Azure Resources entities. Cortex will display those Azure Resources entities' metadata on the Cortex entity page.

When the entity is connected to Azure, the entity YAML will look like the following:

Using the Azure Resources integrations

Scorecards and CQL

With the Azure Resources integration, you can create Scorecard rules and write CQL queries based on Azure Resources details.

See more examples in the in Cortex.

View integration logs

Background sync

Cortex conducts a background sync of Azure Resources every day at 10 a.m. UTC and an ownership sync every day at 6 a.m. UTC.

FAQs and troubleshooting

Why is the Azure resource type microsoft-resources-subscriptions-resourcegroups not pulling in Azure Resource details?

Cortex pulls from the Azure Resource API, but not from the Azure Resource Group API. If you would like to submit a feature request for support of Azure Resource Groups, please contact our customer engineering team.

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

Codecov is a code coverage reporting platform that that monitors how much of your code has been tested and validated. Codecov analytics can be used to drive visibility into your microservice architecture and understand coverage trends over time.

Integrating Cortex with Codecov allows you to:

• View code coverage details for entities directly in Cortex

• Create Scorecards that track progress and drive alignment on projects involving your Codecov code coverage metrics

How to configure Codecov with Cortex

Prerequisites

Before getting started:

• Create a .

Configure the integration in Cortex

1. In Cortex, navigate to the .

   • Click Integrations from the main nav. Search for and select Codecov.

2. Click Add configuration.

3. Configure the Codecov integration form:

How to connect Cortex entities to Codecov

Auto discovery of Codecov projects

Cortex will use the GitHub, GitLab, Bitbucket, or Azure DevOps repository as the "best guess" for the corresponding Codecov project, since Codecov projects are connected to repositories. For example, if the GitHub repo associated with your Codecov instance is my-org/repo, then the entities in Cortex should also be associated with my-org/repo.

You can find the repository for a given entity in its YAML, defined in a block like the one below:

If the Codecov project you want to associate isn't the same as the repository, you can override this in the Cortex entity descriptor.

Editing the entity descriptor

The value for repo should be the full repository because Codecov maps projects by repo.

Flags

Codecov's are used to categorize coverage reports for various features and tests in a given project. Flags allow you to set different statistics for different areas of your code base. For example, if you have a monorepo with multiple unique projects, you can use Codecov flags to evaluate each project with different test coverage metrics.

To pull flags into Cortex, define the flag line in the .

Using the Codecov integration

Entity pages

With the Codecov integration, you can find code coverage details on an entity's details page as long as that entity is associated with a repo linked to your Codecov instance.

Click Code & security in the entity's sidebar to see the code coverage for that entity.

Scorecards and CQL

With the Codecov integration, you can create Scorecard rules and write CQL queries based on Codecov code coverage metrics.

See more examples in the in Cortex.

View integration logs

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

In some instances, a Scorecard rule might not apply to an entity. For example, a rule may be linked to an Initiative your team is actively working on and the failure notification may be irrelevant or noisy to developers. Or, in rarer cases, the Scorecard rule may not make sense for a given component, depending on the nature of that entity. In either case, rule exemptions allow you to filter out components that shouldn’t be evaluated by a specific rule.

With rule exemptions, entities are not marked as passing or failing — the rule simply does not apply to those entities. If you use point-based rules instead of levels, the exempted rule will not be included in the average for a component’s percentage score. If you use levels, an exempt rule allows an entity to progress to the next level.

Any user can request a rule exemption, and Admins or users with the Configure Scorecard exemptions permission can approve, deny or revoke a rule exemption. Users with the View Scorecard exemptions permission can view exemptions in Scorecards that have been requested by any user; without that permission, a user can only see their own requested exemptions.

See our knowledge base for best practices on managing rule exemptions.

How to request a rule exemption

Any user can request an exemption. This can be done , or via the Cortex UI.

While viewing a Scorecard in the Cortex UI:

1. Click into an entity on which you want to request a rule exemption.

   • A side panel will open, showing each rule applied to that entity.

2. Next to the rule you want to request an exemption for, click the 3 dots icon, then click Request exemption.\

If the Scorecard has the enabled, then the exemption will automatically be approved.

If the Scorecard has user-specific notifications enabled, you'll need to select a user to notify of the rule exemption request. That user will be able to review, and approve or reject the request. If this field is not enabled, then all Admins will be notified of the request.

Permanent or time-bound exemptions

You’ll use a permanent exemption when there’s no expectation an entity will pass a rule, whereas a time-bound exemption makes more sense when an entity is expected to be in compliance with a given rule by a certain time.

In many cases, a time-bound exemption will be related to an ongoing Initiative. For example, entities might be required to have an on-call rotation set up by the end of the quarter. In this case, a developer may request an exemption that ends a few weeks before the quarter concludes — this can serve as a backup reminder if on-call isn’t set up at that point, and in the meantime, the failing rule won’t add any noise to the developer’s workflow.

When the time period for a temporary exemption elapses, any entities that are not in compliance with the rule would display as failing, while those in compliance would display as passing.

How to approve, deny, or revoke a rule exemption

To approve or deny rule exemptions, you must be an Admin, or you must have a custom role that contains the Configure Scorecard exemptions .

Admins are able to , in addition to .

Auto-approval

If your to enable auto-approval for exemptions, then you do not need to take any action to approve the exemption.

After the user submits an exemption request, the exemption will appear in the Scorecard's Exemptions tab as Exempt, with the option to revoke the exemption appearing on the right side of the rule:

Also note that if you are an admin user and you request an exemption, it will automatically approve.

Manual approval

If you have for rule exemption requests, then you will receive a notification when a user requests an exemption. The notification includes the name of the requestor, the rule name and its Scorecard, the entity that the exemption applies to, the reason and timeframe provided by the requestor, and a direct link to approve or deny the request in Cortex.

If you do not have notifications enabled, you can (in Scorecard's Exemptions tab or under Settings > Scorecards > Rule exemptions) and then accept, reject, or revoke from there.

API

You can , , or a Scorecard rule exemption via the API.

View exempted rules

Admins, or users with the Configure Scorecard exemptions , can view exemption requests, approve or deny the request, and revoke exemptions.

View exemptions in a Scorecard

When viewing a Scorecard, click into the Exemptions tab to view requests for exemptions and rules that have already been exempted:

View all exemptions

In , admins can view a list of all requested exemptions:

Learn about CQL basics and CQL tools (Query builder and CQL explorer) in Cortex Query Language (CQL).

Running a CQL query

The Query builder allows you to define your query without needing to learn CQL upfront.

You will need the Run query builder permission. If you are running queries on third-party integrations, you will also need the Run query builder with third-party integrations permission.

Step 1: Build a query

1. On the right side of the Query builder page, click the CQL builder tab. \
2. In the CQL builder, choose and integration and a rule to evaluate.

   • The rules available in the dropdown menu will depend on the integration you've selected.

Step 2: Test the query

1. Under the CQL text editor on the left, select an entity to test the query against.

2. Click Test.

   • The results appear under the text editor. Review the results to verify that the query is working as you expect. \

Step 3: Run the query

1. In the lower right corner of the page, click Run query.

2. In the side panel that opens, choose whether to run the query on all entities or select specific entities.

3. At the bottom of the side panel, click Run query.

4. In the confirmation modal that appears, click Yes, run query.

View and share results

After running the query, the page displays a list of all entities matching the criteria. In the upper right corner of the list, you can sort and filter the list. As you apply filters to your list, Cortex will also update the number of matching entities, so you can easily see at a glance how many entities match your requirements.

You can share the results in two ways:

• Send a link: Click Share in the upper right corner of the results list to copy the URL to your clipboard. You can share the link with anyone who has access in your Cortex workspace.

• Export as CSV: In the upper right corner of the page, click Export CSV to download a CSV file of the data.

Running rules on multiple queries

If you want to run a query on more than one rule, you can join multiple queries together with AND and OR.

For example:

CQL errors

The following errors may occur when running a CQL query:

• 400: This typically indicates a misconfiguration with an integration. For example, you may be missing an entity registration required for an integration.

• 403: This occurs if there are missing or improper .

• 429: This occurs when hitting the rate limit for an integration. Cortex will retry 5 times before responding with this error. To prevent rate limit issues, we have built a self-throttling system that proactively throttles before hitting a rate limit from the vendor.

Save a query

While viewing the results of a query you ran, you can save the query to use again in the future:

1. In the upper right corner of the results page, click Save query.\
2. In the side panel, configure the query details:

   • Enter a name and description for your query.

View active, recent, and saved queries

Below the CQL search text box, you can see active queries. This section displays the ongoing process of your submitted query. When the query is complete, it will appear under Recent.

Along the top of the query builder, you can click into tabs to view Saved and Recent queries. Click into any of the queries in these lists to view the results of the query.

Saved queries

Click the Saved tab to view a list of your saved queries, and queries that others have saved and shared across your organization.

Query results are not automatically updated, but you can refresh a query manually: While viewing the results page, click the 3 dots icon, then click Refresh.

Recent queries

Click the Recent tab. This list shows all queries that have been run in the last 30 days.

LaunchDarkly is a feature flag management platform.

Integrating Cortex with LaunchDarkly allows you to:

• Track LaunchDarkly feature flags on entities in the catalog.

• Create Scorecards that track progress and drive alignment on projects involving your LaunchDarkly feature flags.

• Perform tasks relating to LaunchDarkly feature flags as a part of a Workflow.

  • For example, you can include a "Create feature flag" step within a Workflow.

How to configure LaunchDarkly with Cortex

Prerequisites

Before getting started, create a with:

• The Writer role

  • If you are not adding LaunchDarkly-related tasks to your , you can configure the token with the Reader role.

• 20220603 as the API version

Configure the integration in Cortex

1. In Cortex, navigate to the :

   • Click Integrations from the main nav. Search for and select LaunchDarkly.

2. Click Add configuration.

3. Configure the integration details:

Configure the integration for multiple LaunchDarkly accounts

The LaunchDarkly integration has multi-account support. You can add a configuration for each additional organization, instance, or account by repeating the process above.

Each configuration requires an alias, which Cortex uses to correlate the designated organization, instance, or account with registrations for various entities. Registrations can also use a default configuration without a listed alias. You can edit aliases and default configurations from the LaunchDarkly page in your Cortex settings. Select the edit icon next to a given configuration and toggle Set as default on. If you only have one configuration, it will automatically be set as the default.

How to connect Cortex entities to LaunchDarkly

Discovery

By default, Cortex will try to "best-guess" the corresponding project in LaunchDarkly based on the key or tags.

Cortex first looks up a LaunchDarkly project using the entity name (e.g. My Service), then the entity identifier (e.g. my-service). For example, if your entity name is “My Service”, then the corresponding LaunchDarkly project's key or tag should contain either “My Service” or "my-service".

If no project was matched, Cortex will try to "best-guess" feature flags from all available projects using feature flag tags.

Editing the entity descriptor

You can find the project key and tags in LaunchDarkly under Account settings > Projects. The URL for the project will contain the key. For example: https://app.launchdarkly.com/projects/default/settings/environments.

If you prefer to use the project tags in the registration instead, you can find it in the projects table or project settings page.

Using the LaunchDarkly integration

Scorecards and CQL

With the LaunchDarkly integration, you can create Scorecard rules and write CQL queries based on LaunchDarkly projects.

See more examples in the in Cortex.

View integration logs

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

CQL reports are ideal when you need to extract, analyze, or share detailed data that goes beyond pass/fail checks, and when you want to create reusable, auto-refreshing reports for ongoing visibility. They allow you to query and visualize raw data from your entities via CQL with more flexibility than what Scorecards or Query Builder provide:

• View any expression result, such as the exact number of incidents, deployment counts, or custom data values for each entity

  • Scorecards and Query Builder require expressions to evaluate to a boolean.

• that aggregate and display data from entity metadata, integrations and custom data

• by surfacing the underlying data that drives rule outcomes

• Export filtered data for further analysis or sharing

Create a CQL report

You will need the Run query builder permission. If you are running queries on third-party integrations, you will also need the Run query builder with third-party integrations permission.

1. In the main nav of Cortex, click Tools > CQL reports. In the upper right corner of the page, click Create CQL report.

2. Choose whether to start from scratch or use a template.

   • If you opt to work from a template, you’ll be able to select from any of your organization’s available templates — along with templates built into Cortex — making it easier to ensure all best practices are being followed.

Note that if the return value is too large (like a 5 MB JSON file) the cell in the report results will error out, so we recommend defining raw values for outputs. The maximum data size that can be the value of a cell is 2048 bytes.

View CQL reports

You can view previously created CQL reports at Tools > CQL reports. Click into a report name to view its results.

Sort and filter CQL reports

You can sort by each column of the report, select which columns are displayed, and filter by AWS account, AWS region, domain, entity, entity type, group, owner, or team.

By default the report displays all entities. Click the Mine tab to view information for only your owned entities.

Share CQL reports

You may need to share a CQL report with teams or leaders to provide detailed, custom insights into entity data, compliance, or operational metrics. Click Export CSV in the upper right corner of the report to generate a CSV file.

A report must be set to Public in order to share it.

Refresh a CQL report

Cortex does not automatically refresh a CQL report. If you did not configure auto refresh for the report, you can refresh it manually: While viewing the results page, click the 3 dots icon, then click Refresh CQL report.

If a report contains expressions written using an outdated version of CQL, you will see a warning banner at the top of the page stating that the report cannot be refreshed. After you update any outdated CQL queries, you will be able to refresh the report.

Enable auto refresh for CQL reports

While , you can schedule an auto refresh. By default, auto refresh is disabled.

If you didn't add auto refresh when creating the CQL report, you can also edit the report later on to enable the setting.

With auto refresh enabled, in the upper right corner of a CQL report page, you will see the last refresh time and the next scheduled evaluation:

Edit a CQL report

To edit an existing CQL report:

1. Navigate to Tools > CQL Reports. Click the CQL report you want to edit.

2. In the upper right corner of the CQL report, click Edit.

3. Make any necessary changes, then at the bottom of the page, click Save.

Using CQL reports to debug Scorecards

You can use CQL reports to help interpret unexpected results from Scorecards.

For example, let's say you have a service that is failing the rule Readme created. However, you believe the service does have a readme file, and you aren't sure why it's failing this rule.

• We could create a CQL report from scratch and add a new column for the README CQL expression to check for README.md in the git repo:

• After saving the CQL report, you can view the results to see the contents of readme files for each entity. In this report, you will be able to see if the readme contains an error such as "The result is too large to store," which would explain why the entity is failing that rule in the Scorecard.

Rollbar is an error tracking tool that helps developers discover and resolve crashes and errors.

Integrating Rollbar with Cortex allows you to:

• View errors on entity pages in Cortex, giving you insight into your entity's operational maturity

• Create Scorecards that include rules relating to error data from Rollbar, motivating team members to improve their code quality

How to configure Rollbar with Cortex

Prerequisites

Before getting started:

• Create a .

  • The token requires read permissions at minimum. This allows Cortex to automatically look up project tokens for each Rollbar project and attempt to reuse them to access project details.

  • Granting the token read and write permissions enables Cortex to automatically create an access token if none exists for a given project.

Configure the integration in Cortex

1. In Cortex, navigate to the :

   1. Click Integrations from the main nav. Search for and select Rollbar.

2. Click Add configuration.

3. Configure the integration form:

After saving your configuration, you are redirected to the Rollbar integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Rollbar was configured properly.

How to connect Cortex entities to Rollbar projects

Discovery

By default, Cortex will use the (e.g. my-entity) as the "best guess" for Rollbar projects. For example, if your Cortex tag is my-entity, then the corresponding project in Rollbar should also be my-entity.

If your Rollbar projects don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor.

Editing the entity descriptor

You can define projects under the x-cortex-rollbar block in an :

Using the Rollbar integration

Viewing Rollbar errors on an entity

Error data from Rollbar will appear on an . In an entity's sidebar, click Error tracking to view detected issues for each Rollbar project. At the top of the page, see the associated project tag and the project framework.

Under Items, see a list of detected errors and their statuses. Next to the error name, you can also see badges for # seen and the type of event: error, warning, or info.

Scorecards and CQL

With the Rollbar integration, you can create Scorecard rules and write CQL queries based on Rollbar projects.

See more examples in the in Cortex.

View integration logs

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

Apiiro is an application security posture management (ASPM) platform that helps you understand and manage application security risks.

Integrating Apiiro with Cortex allows you to:

• View risks on entity pages in Cortex, quickly connecting issues to entities and their owners

• Use Scorecards to drive quality improvements to your security practices relating to Apiiro applications, and set Initiatives to prioritize tasks and set deadlines.

How to configure Apiiro with Cortex

Prerequisites

Before getting started:

• Create an . Include the following permissions:

  • Risks > Read

  • Inventory management > Applications > Read

Configure the integration in Cortex

1. In Cortex, navigate to the .

   • Click Integrations from the main nav. Search for and select Apiiro.

2. Click Add configuration.

3. Configure the integration form:

After saving your configuration, you are redirected to the Apiiro integration settings page in Cortex. In the upper right corner of the page, click Test configuration to ensure Apiiro was configured properly.

How to connect Cortex entities to Apiiro

Discovery

Cortex uses the entity name, , or repository as the "best guess" for the corresponding Apiiro application. For example, if your entity name is "My Service" or your tag is my-service, then the corresponding application name in Apiiro should also be My Service or my-service.

If your Apiiro application names don’t cleanly match the Cortex entity name or tag, you can override this in the Cortex entity descriptor.

Editing the entity descriptor

You can define repositories and applications in the under the x-cortex-apiiro block:

Using the Apiiro integration

Viewing Apiiro risks on an entity

Entity page overview

On an overview, see risks listed under the Code & security block. Within this block, issues and vulnerabilities are grouped by severity: Critical, High, Medium, and Low. Click into any of these to open a list of all applicable issues and vulnerabilities.

Entity code & security sidebar

In an entity's sidebar, click Code & security > Apiiro to view risks from Apiiro.

Scorecards and CQL

With the Apiiro integration, you can create Scorecard rules and write CQL queries based on Apiiro risks.

See more examples in the in Cortex.

View integration logs

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

Overview

Checkmarx is an automated application security platform that checks source code for security vulnerabilities and compliance issues. Integrate Cortex with Checkmarx to drive insight into the vulnerabilities detected on your entities.

This integration is supported for Checkmarx Static Application Security Testing (SAST).

How to configure Checkmarx with Cortex

Prerequisites

Before getting started, create a user with access to the sast_rest_api scope.

Configure the integration in Cortex

1. In Cortex, navigate to the .

   • Click Integrations from the main nav. Search for and select Checkmarx.

2. Click Add configuration.

3. Configure the Checkmarx integration form:

How to connect Cortex entities to Checkmarx

Discovery

By default, Cortex will use your associated Git repository (e.g. repo-name) or the service tag as the "best guess" for the Checkmarx project name.

If your repository and entity names don’t cleanly match the Checkmarx CxSAST project names, or if you have multiple Checkmarx projects for a service, you can add a Checkmarx project ID (recommended) or a Checkmarx project name in the Cortex entity descriptor.

Editing the entity descriptor

We recommend using the project ID as it is a unique identifier across projects.

Example using project IDs:

Example using both project IDs and names:

Using the Checkmarx integration

Entity pages

Once the integration is established, vulnerabilities pulled from Checkmarx will be available for each entity in the Code and Security block in the Overview tab.

While viewing an entity, click Code & security > Checkmarx. On this page, view the number of vulnerabilities per severity and a link directly to your Checkmarx instance.

Scorecards and CQL

With the Checkmarx integration, you can create Scorecard rules and write CQL queries based on Checkmarx details.

See more examples in the in Cortex.

View integration logs

FAQs and troubleshooting

Does Cortex support integrating with Checkmarx One?

No, Cortex does not currently support Checkmarx one. Only Checkmarx SAST is supported for this integration.

Still need help?

The following options are available to get assistance from the Cortex Customer Engineering team:

• Email: , or open a support ticket in the in app Resource Center

• Slack: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a :ticket: reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.

The teams getting the most value from the MCP have developed prompt patterns that fit naturally into their workflows. We've collated the most effective prompt patterns we've seen across different roles and workflows to build the list of prompt examples below. Think of it as a starting point for building your own prompt library, one that fits the specific needs of your team and organization.

Prompts for engineers

The best prompts for engineers eliminate context switching at the moments when focus matters most.

is a declarative, GitOps continuous delivery tool for Kubernetes.

Integrating Cortex with ArgoCD allows you to:

• Send information about ArgoCD syncs into Cortex

  • This data appears on .

• Use

is an application monitoring platform that helps developers identify, debug, and resolve issues.

Integrating Sentry with Cortex allows you to:

• , giving you insight into your entity's operational maturity

• , using the Cortex Slack Bot

• Create that include rules related to Sentry errors

is an automated security platform that identifies and remediates vulnerabilities in software applications. DAST, SAST, and SCA are supported.

Integrating Veracode with Cortex allows you to:

• in Cortex

• Create that track progress and drive alignment on Veracode vulnerability metrics

Overview

is an open-source monitoring and analytics platform that allows customers to analyze, visualize, automate, and alert on metrics data.

Integrating Cortex with Prometheus allows you to:

• from Prometheus on entity pages in Cortex

Splunk On-Call (formerly known as ) is an alert and on-call management platform.

Integrating Cortex with Splunk On-Call allows you to:

• Pull in on-call rotation data and escalation policies

  • The on-call user or team will appear in the Current On-call block on an entity's details page.

The Scorecard use cases and examples this is section are based on engineering teams across a wide spectrum of sizes and maturity levels. Learn and what look like.

See additional detailed examples in the :

Custom webhook integrations allow you to POST data to a unique endpoint in Cortex, map the payload to existing entities, and make that data available for use in , , and on .

Using a custom webhook is especially helpful if:

• You have internal tools, homegrown systems, or third-party services that Cortex doesn't integrate with yet.

• You want to automate the process of sending custom metrics, events, or other data into Cortex without building and maintaining additional infrastructure.

, formerly known as Azure Active Directory, is an identity service that provides SSO and authentication.

Integrating Cortex with Entra ID allows you to:

• Automatically discover and track Entra ID teams and team memberships

• Track ownership of entities

• Create that track progress and drive alignment on projects involving your Entra ID teams

is an application stability monitoring platform that provides error tracking and analytics.

Integrating BugSnag with Cortex allows you to:

• in Cortex, giving you insight into your entity's operational maturity

• Create that include rules related to BugSnag errors

is static application security testing (SAST) tool that includes software composition analysis (SCA). It detects security vulnerabilities in your code and analyzes your open-source dependencies for vulnerabilities. You can use it to scan local repositories or integrate it into your CI/CD pipeline.

Integrating Semgrep with Cortex allows you to:

• Display the latest scans and vulnerability data

• Create that track progress and drive alignment on projects involving Semgrep security data, allowing you to address and remediate vulnerabilities more efficiently

Splunk Observability Cloud () is a monitoring and analytics platform that allows customers to evaluate, visualize, automate, and alert on metrics.

Integrating Splunk Observability Cloud with Cortex allows you to:

• in Cortex

• Create that include rules related to your Splunk Observability Cloud SLOs