Skip to main content

Check out Port for yourself ➜ 

Checkmarx One

Loading version...

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

Supported resources ProjectScanSASTSCAKICSContainer SecurityAPI SecurityApplication

Prerequisites​

  • A Checkmarx One enterprise account.
  • A Port organization with admin permissions.
Checkmarx One API Access

The Checkmarx One API is available for enterprise customers. You need an API key to authenticate with the Checkmarx One API.

Checkmarx One Credentials​

You need the following connection details to configure Checkmarx One:

  • Checkmarx One Base URL: The API endpoint URL for your region.
  • Checkmarx One IAM URL: The IAM authentication URL for your region.
  • Tenant Name: Your Checkmarx One tenant name.
  • API Key: Your Checkmarx One API key.
Regional URLs (click to exapnd)

Checkmarx One provides different URLs based on your region:

  • US: https://ast.checkmarx.net/api / https://iam.checkmarx.net
  • EU: https://eu.ast.checkmarx.net/api / https://eu.iam.checkmarx.net
  • US2: https://us.ast.checkmarx.net/api / https://us.iam.checkmarx.net
  • EU2: https://eu-2.ast.checkmarx.net/api / https://eu-2.iam.checkmarx.net
  • DEU: https://deu.ast.checkmarx.net/api / https://deu.iam.checkmarx.net
  • ANZ: https://anz.ast.checkmarx.net/api / https://anz.iam.checkmarx.net
  • IND: https://ind.ast.checkmarx.net/api / https://ind.iam.checkmarx.net
  • SNG: https://sng.ast.checkmarx.net/api / https://sng.iam.checkmarx.net
  • UAE: https://mea.ast.checkmarx.net/api / https://mea.iam.checkmarx.net

  1. Finding Your Checkmarx One Base URL and IAM URL:

    • Login to your Checkmarx One account.
    • Navigate to Settings > Identity and Access Management.
    • The base URL and IAM URL will be displayed based on your region.
    • Copy and save both URLs for use in the integration configuration.

  2. Getting Your Tenant Name:

    • Your tenant name is typically part of your login URL.
    • It can also be found in your account settings.
    • Copy and save your tenant name.

  3. Generating an API Key:

    • Login to Checkmarx One with admin permissions.
    • Navigate to Settings > Identity and Access Management > API Keys.
    • Click Add API Key.
    • Provide a descriptive name for the API key.
    • Select the appropriate permissions (read access to projects, scans, and results).
    • Click Create API Key.
    • Copy and securely store the generated API key.
API Key Security

Store your API key securely and never share it. The API key provides access to your Checkmarx One data.

Setup​

Choose one of the following installation methods: Not sure which method is right for your use case? Check the available installation methods.

Setting up webhooks for live events​

To enable real-time updates from Checkmarx One to your Ocean integration, configure a webhook in your Checkmarx One instance. This allows Port to receive notifications when projects are created or scans complete, keeping your software catalog synchronized. Live events are supported for projects, scans, and all scan result types (SAST, SCA, KICS, Container Security, and API Security).

You can configure webhooks at two levels: tenant-level for organization-wide monitoring, or project-level for specific projects.

Tenant-level webhooks receive events from all projects and support project creation events. For more details, see the Checkmarx tenant-level webhooks documentation.

  1. Log in to your Checkmarx One account with admin permissions.
  2. Click the gear icon and select Global Settings.
  3. Select Webhooks from the menu, then click Add Webhook.
  4. Fill in the webhook details:
    • Name: Enter a descriptive name (e.g., Port Integration Webhook).
    • Payload URL: Enter the URL where your integration is accessible, following the pattern https://<YOUR_INTEGRATION_HOST>/integration/webhook (replace <YOUR_INTEGRATION_HOST> with your integration's host address).
    • Secret (optional): Enter a secret to secure webhook deliveries. If configured, set the same value in the webhookSecret parameter of your integration.
    • Events: Select Project Created, Completed Scan, Failed Scan, and Partial Scan.
  5. Click Add Webhook to save.
Webhook security

For added security, configure a webhook secret in Checkmarx One and set the same secret in your integration configuration using the webhookSecret parameter. This ensures that the integration only accepts legitimate events from Checkmarx One.

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.

Default mapping configuration​

This is the default mapping configuration for this integration:

Default mapping configuration (click to expand)
createMissingRelatedEntities: true
deleteDependentEntities: true
resources:
  - kind: project
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"checkmarxProject"'
          identifier: .id
          title: .name
          properties:
            name: .name
            createdAt: .createdAt
            updatedAt: .updatedAt
            tags: (.tags // {})
            repoUrl: .repoUrl
            mainBranch: .mainBranch
            origin: .origin
            criticality: .criticality

  - kind: scan
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          blueprint: '"checkmarxScan"'
          identifier: .id
          title: '(.projectId + "-" + .id)'
          properties:
            status: .status
            branch: .branch
            createdAt: .createdAt
            updatedAt: .updatedAt
            projectId: .projectId
            userAgent: .userAgent
            configs: (.configs // {})
            statusDetails: (.statusDetails // [])
          relations:
            project: .projectId

  - kind: sast
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .resultHash
          title: .queryName
          blueprint: '"checkmarxSast"'
          properties:
            firstScanId: .firstScanID
            status: .status
            state: .state
            severity: (.severity // empty)
            confidenceLevel: .confidenceLevel
            created: .firstFoundAt
            nodes: (.nodes // empty)
            cweId: (.cweID // empty)
          relations:
            scan: .scanID

  - kind: sca
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .data.packageIdentifier
          blueprint: '"checkmarxSCA"'
          properties:
            firstScanId: .firstScanId
            status: .status
            state: .state
            severity: .severity
            created: .created
            description: .description
            packageIdentifier: .data.packageIdentifier
            recommendations: .data.recommendations
            recommendedVersion: .data.recommendedVersion
            packageData: .data.packageData
            cweId: .vulnerabilityDetails.cweId
          relations:
            scan: .__scan_id

  - kind: kics
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .description
          blueprint: '"checkmarxKics"'
          properties:
            type: .type
            firstScanId: .firstScanId
            id: .id
            status: .status
            state: .state
            severity: (.severity // empty)
            confidenceLevel: .confidenceLevel
            created: .created
            description: .description
            fileName: (.data.fileName // empty)
            line: (.data.line // empty)
            platform: (.data.platform // empty)
            issueType: (.data.issueType // empty)
            expectedValue: (.data.expectedValue // empty)
            value: (.data.value // empty)
        relations:
          scan: .__scan_id

  - kind: containers
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .id
          title: .id
          blueprint: '"checkmarxContainerSecurity"'
          properties:
            firstScanId: .firstScanId
            status: .status
            state: .state
            severity: .severity
            confidenceLevel: .confidenceLevel
            created: .created
            description: .description
            packageName: .data.packageName
            packageVersion: .data.packageVersion
            imageName: .data.imageName
            imageTag: .data.imageTag
            imageFilePath: .data.imageFilePath
            cweId: .vulnerabilityDetails.cweId
          relations:
            scan: .__scan_id

  - kind: apisec
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .risk_id
          title: .name
          blueprint: '"checkmarxApiSec"'
          properties:
            riskId: .risk_id
            apiId: .api_id
            severity: (.severity // empty)
            name: .name
            status: .status
            httpMethod: .http_method
            url: .url
            origin: .origin
            documented: .documented
            authenticated: .authenticated
            discoveryDate: .discovery_date
            scanId: .scan_id
            sastRiskId: (.sast_risk_id // empty)
            projectId: .project_id
            state: .state
        relations:
          scan: .scan_id

Deep links to Checkmarx One dashboard

If you need to ingest deep links back to the Checkmarx One dashboard, you can construct them using jq expressions in your mapping configuration. Combine your Checkmarx One UI base URL with relevant path parameters from the data returned by the API.

For example, to create a dashboard link for a project:

dashboardUrl: '"https://your-region.ast.checkmarx.net/projects/" + .id'

Or for a specific scan result:

scanUrl: '"https://your-region.ast.checkmarx.net/projects/" + .projectId + "/scans/" + "?id=" + .id'

Replace your-region with your actual Checkmarx One region (e.g., eu, us, deu, etc.) and adjust the path structure based on your Checkmarx One dashboard URL format.

Mapping & examples per resource​

Use the explorer below to view the mapping and blueprint definition for each resource type. For additional resources and advanced configurations, see the examples page.

Monitoring and sync status​

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

Examples​

To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your data sources page. Find the integration in the list of data sources and click on it to open the playground.

Examples of blueprints and the relevant integration configurations can be found on the Checkmarx examples page.

Resource Configuration​

The Checkmarx One integration supports filtering and configuration for different resource types:

Project resources

Projects can be synchronized without additional filtering options.

Scan resources

Scans can be filtered using the following scan filter options:

  • Project Names (projectIds): Filter scans by their project name
  • Branches: Filter results by the name of the Git branch that was scanned
  • Statuses: Filter results by the execution status of the scans (case insensitive, OR operator for multiple statuses):
    • Queued
    • Running
    • Completed
    • Failed
    • Partial
    • Canceled
  • Since: Filter results by the date and time when the scan was created (UNIX timestamp in seconds, default: 90 days)

Security Scan Results (SCA/Containers) configuration

You can configure security scan results (SCA, Container Security) with the following filters:

  • Scan Filter: Apply the same scan filtering options as above
  • Severity: Filter by severity level (CRITICAL, HIGH, MEDIUM, LOW, INFO)
  • State: Filter by state:
    • TO_VERIFY
    • CONFIRMED
    • URGENT
    • NOT_EXPLOITABLE
    • PROPOSED_NOT_EXPLOITABLE
    • FALSE_POSITIVE
  • Status: Filter by status (NEW, RECURRENT, FIXED)
  • Exclude Result Types: Filter to exclude dev and test dependencies (DEV_AND_TEST, NONE)

SAST (Static Application Security Testing) configuration

SAST results can be configured with comprehensive filtering options:

  • Scan Filter: Apply the same scan filtering options as above
  • Compliance: Filter by compliance standard (exact match, case insensitive)
  • Group: Filter by vulnerability group (substring match)
  • Include Nodes: Include or omit node data (default: true)
  • Language: Filter by language (exact match, case insensitive)
  • Result ID: Filter by unique result hash
  • Severity: Filter by severity level (critical, high, medium, low, info)
  • Status: Filter by status (new, recurrent, fixed)
  • Category: Filter by comma separated list of categories
  • State: Filter by state:
    • to_verify
    • not_exploitable
    • proposed_not_exploitable
    • confirmed
    • urgent

KICS (Infrastructure as Code Security) configuration

KICS results can be configured with the following filters:

  • Scan Filter: Apply the same scan filtering options as above
  • Severity: Filter KICS results by severity levels (CRITICAL, HIGH, MEDIUM, LOW, INFO)
  • Status: Filter KICS results by status (NEW, RECURRENT, FIXED)

API security configuration

API security results can be configured with:

  • Scan Filter: Apply the same scan filtering options as above

Application resources

Applications can be filtered using the following filter options:

  • Tag Keys: Filter results by the tag keys of the application
  • Tag Values: Filter results by the tag values of the application

Troubleshooting​

Common Issues​

  1. Authentication Errors: Ensure your API key is valid and has the correct permissions.
  2. Regional URL Issues: Verify you're using the correct base URL and IAM URL for your region.
  3. Tenant Name Issues: Make sure your tenant name is correctly specified.
  4. Permission Issues: Ensure your API key has read access to projects, scans, and results.

Logs and debugging​

The integration provides detailed logging for debugging:

  • Check the integration logs for authentication and API request details.
  • Verify that the correct URLs and credentials are being used.
  • Monitor for any rate limiting or permission errors.

For more detailed troubleshooting, refer to the Checkmarx One API documentation.