Internally hosted integrations

• Custom handlers - Write code against the Cortex API that sends data to Cortex on a set interval, on a cron schedule, or after processing a webhook. For more information, see the Cortex Axon README.
• Internally-hosted integrations - Axon Relay creates a virtual connection between your network and Cortex, so Cortex can reach integrations you host internally. Axon Relay supports Bitbucket, GitHub, GitLab, Google Cloud Platform, Harness, Jira, Prometheus, and SonarQube. You can also use it to call internal service endpoints from a Workflow.

​

How Axon Relay works

1. In Cortex, you register the integration with an alias you choose.
2. You start the Cortex Axon Docker container with your Cortex API key, the integration type, and the alias.
3. The Axon agent connects to Cortex, authenticates, and registers itself with the integration type and alias.
4. The agent starts a Snyk Broker client process. The client uses the configuration details returned by that registration (the /register call) to connect to the Snyk Broker server that runs on the Cortex backend.
5. Once the connection is established, Cortex relays API calls to your internal network, and the responses come back to Cortex through the same tunnel.

​

Using Axon Relay

​

Prerequisites

1. Create an API key in Cortex.
2. Create authentication credentials for the integration you’re configuring. Refer to the third-party’s documentation for more information.

​

Step 1: Setting up the Cortex Axon agent

​

Step 1.1: Configuring the Axon Relay in Cortex

1. From the main sidebar, expand Integrations, then select Configurations.
2. Search for the integration you want to set up, then click +Install.
   
3. In the side panel, select Relay as the configuration type.
4. From Configuration details, do the following:
   1. Optionally, select a new category from the Category dropdown. Cortex provides a default category, you can change it if you need to. Needs at least one category.
   2. Configuration alias - Enter the alias that ties the service registration to this configuration (required).
   3. Depending on the integration, there may be additional options to configure.

​

Step 1.2: Creating a .env file and a docker-compose.yml file

1. Locally on your machine, create a file called .env. Inside the file, add contents for the integration you are configuring:
   
   Docker Compose

   See the variables for your integration in the README. For example, for GitLab you would add:

   CORTEX_API_TOKEN=your_cortex_token
   GITLAB_TOKEN=your_gitlab_token
   

   Kubernetes

   To run the agent in Kubernetes, you’ll need to create a Deployment that runs the agent with similar configuration as described above. There is a Helm chart available that can be used as a starting point. Its critical variables are:

   # Example for github
   relay:
     integration: github # can be blank
     subtype:   # optional, can be blank, see table above for options
     alias: alias for configuration from Cortex
     env:
       GITHUB: "https://github.com"
       GITHUB_API: "https://api.github.com"
       GITHUB_GRAPHQL_API: "https://api.github.com/graphql"
     verbose: false # set to true to enable verbose logging
   

   If you have a proxy setup you can add values such as:

   proxy:
     server:  http://proxy.example.com:8080
     noProxy: proxy.example.com # note localhost is added automatically
     certSecretName: my-proxy-ca-pem # name of the secret containing a .pem file with the CA certificate
   

2. Locally on your machine, create a file called docker-compose.yml. Inside the file, add contents for the integration you are configuring:
   
   Bitbucket

   Bitbucket Cloud:

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - BITBUCKET_API=https://api.bitbucket.org
         - BITBUCKET_TOKEN=<token>
       command: [
         "relay",
         "-i", "bitbucket",
         "-a", "bitbucket-relay", # this is the alias you set up in the Cortex UI
       ]
   

   Bitbucket Hosted:

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - BITBUCKET_API=https://bitbucket.mycompany.com
         - BITBUCKET_USERNAME=<user>
         - BITBUCKET_PASSWORD=<password>
       command: [
         "relay",
         "-i", "bitbucket",
         "-a", "bitbucket-relay", # this is the alias you set up in the Cortex UI
       ]
   

   GitHub

   GitHub:

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - GITHUB_API=api.github.com
         - GITHUB_GRAPHQL=api.github.com/graphql
       command: [
         "relay",
         "-i", "github",
         "-a", "github-relay", # this is the alias you set up in the Cortex UI
   
         # if you are using a Github App token, add the following line
         # "-s", "app",
       ]
   

   Additional environment variables include: GITHUB_API=https://api.github.com, GITHUB_TOKEN GitHub Hosted:

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - GITHUB_API=https://github.mycompany.com/api/v3
         - GITHUB_GRAPHQL=https://github.mycompany.com/api/graphql
       command: [
         "relay",
         "-i", "github",
         "-a", "github-relay", # this is the alias you set up in the Cortex UI
   
         # if you are using a Github App token, add the following line
         # "-s", "app",
       ]
   

   Additional environment variables include: GITHUB=https://github.mycompany.com, GITHUB_TOKEN GitHub App:

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - GITHUB_API=https://api.github.com
         - GITHUB_GRAPHQL=https://api.github.com/graphql
       command: [
         "relay",
         "-i", "github",
         "-a", "github-relay", # this is the alias you set up in the Cortex UI
   
         # if you are using a Github App token, add the following line
         # "-s", "app",
       ]
   

   Additional environment variables include: Arg -s app, GITHUB=https://github.com, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_PEM (either path to PEM or PEM contents), GITHUB_INSTALLATION_ID

   GitLab

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - GITLAB_API=https://gitlab.com
         - GITLAB_TOKEN=<token>
       command: [
         "relay",
         "-i", "gitlab",
         "-a", "gitlab-relay", # this is the alias you set up in the Cortex UI
       ]
   

   Google Cloud Platform (GCP)

   The Google Cloud agent doesn’t use a token or password in .env. It gets short-lived credentials from Application Default Credentials (ADC) in your environment. The alias must be gcp. Service account key: Mount the key file into the container and point GOOGLE_APPLICATION_CREDENTIALS to it.

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       volumes:
         - ./gcp-service-account.json:/etc/gcp/credentials.json:ro
       environment:
         - GOOGLE_APPLICATION_CREDENTIALS=/etc/gcp/credentials.json
       command: [
         "relay",
         "-i", "google",
         "-a", "gcp", # must be gcp
       ]
   

   GKE Workload Identity: You don’t need to mount anything. The container reaches the GKE metadata server over pod networking.

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       command: [
         "relay",
         "-i", "google",
         "-a", "gcp", # must be gcp
       ]
   

   Harness

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - HARNESS_API=https://app.harness.io # for self-managed, set to your internal host
         - HARNESS_TOKEN=<your_harness_api_key>
       command: [
         "relay",
         "-i", "harness",
         "-a", "harness-relay", # this is the alias you set up in the Cortex UI
       ]
   

   Jira

   Jira:

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - JIRA_API=https://jira.mycompany.com
         - JIRA_USERNAME:<user>
         - JIRA_TOKEN=<token>
       command: [
         "relay",
         "-i", "jira",
         "-a", "jira-relay", # this is the alias you set up in the Cortex UI
       ]
   

   Jira Bearer/Cloud:

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - JIRA_API=https://mycompany.atlassian.com
         - JIRA_TOKEN=<token>
       command: [
         "relay",
         "-i", "jira",
         "-a", "jira-relay", # this is the alias you set up in the Cortex UI
       ]
   

   Additional variables include: Arg -s bearer

   Prometheus

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - PROMETHEUS_API=http://mycompany.prometheus.internal
         - PROMETHEUS_USERNAME=<user>
         - PROMETHEUS_PASSWORD=<password>
       command: [
         "relay",
         "-i", "prometheus",
         "-a", "prometheus-relay", # this is the alias you set up in the Cortex UI
       ]
   

   SonarQube

   services:
     axon:
       image: ghcr.io/cortexapps/cortex-axon-agent:latest
       env_file: .env
       environment:
         - SONARQUBE_API=https://sonarqube.mycompany.com
         - SONARQUBE_TOKEN=<token>
       command: [
         "relay",
         "-i", "sonarqube",
         "-a", "sonarqube-relay", # this is the alias you set up in the Cortex UI
       ]
   

​

Step 2: Running the agent

• In a production environment
  • Use the Helm chart provided by Cortex.
• In a sandbox environment
  1. In your CLI, run the command docker compose up.
     The agent starts and connects to Cortex.
  2. Verify that your agent is working:
     1. From the main sidebar in Cortex, expand Integrations, then select Configurations.
     2. Locate the integration, then click Settings.
     3. On the integration’s Settings page, click Test all at the top right.
        • If watching the logging output in your CLI, you’ll see the agent receive the request and forward it to your internal service.
        • Check the message in the bottom-right corner of the screen to see whether the test succeeded.

​

Examples