Cortex CLI Cortex Cloud Application Security command line reference

Reference commands and flags for Cortex Cloud Application Security scans.

Use these command-line flags to configure Cortex Cloud Application Security scans. They are scoped to the code scan command and define what to scan and how results are reported. Their environment variables use the CORTEX_CODE_ prefix. The Application Security CLI also accepts flags that apply across modules, including authentication, TLS, proxy, logging, upload behavior, and exit-code policy.

--upload-mode and --no-fail-on-crash are the only flags supported in both global and command positions. They use the global variables $CORTEX_UPLOAD_MODE and $CORTEX_NO_FAIL_ON_CRASH, not CORTEX_CODE_ variables. Command-position support is retained for backward compatibility.

For global and common CLI commands, refer to Cortex CLI common command line reference guide.

Important

The Cortex CLI Cortex Cloud Application Security only supports single occurrences of each flag. If the same flag is passed multiple times, only the last provided value will be used. For example, in the following command, only TF CloudFormation will be the scanned framework.

EXAMPLE

cortexcli --api-base-url <YOUR_API_URL> --api-key <YOUR_API_KEY> --api-key-id <YOUR_API_KEY_ID> code scan --framework terraform --framework "terraform cloudformation

Command/Variable	Description
--source $CORTEX_CODE_SOURCE	(Optional, default CORTEX_CLI) The execution environment that launched the scan. Use one of the following values: CORTEX_CLI, IDE_VSCODE, JENKINS, GITHUB_ACTIONS, CIRCLE_CI, AWS_CODE_BUILD, GIT_HOOK, GIT_HOOK_COMMITS. EXAMPLE: In a GitHub Actions pipeline, pass --source GITHUB_ACTIONS
--repo-id $CORTEX_CODE_REPO_ID	The unique identifier used to associate scan results with the correct repository in Cortex. Value: owner/repo (for example, my-org/my-repo). Value must contain a forward slash / Requirement: Required for upload mode; otherwise, optional Auto-detection: If omitted, the CLI automatically extracts this value from your Git remote URL using the last two segments of the path Do not use the tenant Asset ID hash, as it will fail validation. For more information on how to retrieve the repository ID, refer to How to retrieve the repository ID
--repo-url $CORTEX_CODE_REPO_URL	Optional: URL of the repository being scanned (for example, https://github.com/org/repo). If omitted, the CLI attempts to auto-detect the URL from the local Git remote of the scanned directory
--branch $CORTEX_CODE_BRANCH	The branch name associated with the scan. Default: The branch detected from your local Git checkout in upload mode when upload permissions are valid
--directory $CORTEX_CODE_DIRECTORY	Required. The directory path to scan. Cannot be used together with --file
--file $CORTEX_CODE_FILE	The file path to scan. Cannot be used together with --directory. When using this option, the Cortex CLI will filter runners based on the file type provided. For example, if you specify a .tf file, only the Terraform and secrets frameworks will be included. You can further limit this (for example; skip secrets) by using the --skip-framework argument
--var-file $CORTEX_CODE_VAR_FILE	Variable files to load in addition to the default files. This feature is currently supported for both source Terraform (.tfvars files) and Helm chart scans (for providing custom values or variable overrides). Refer to https://www.terraform.io/docs/language/values/variables.html#variable-definitions-tfvars-files) below for more information
--framework $CORTEX_CODE_FRAMEWORK	Filter to scan specific frameworks. Example: --framework arm. Syntax: Use a single flag with comma-separated values for multiple frameworks. Both quoted ("arm,ansible") and unquoted (arm,ansible) formats are supported. Example: --framework arm,ansible. Constraint: Do not use multiple --framework flags: --framework terraform --framework sca_package. Environment variables: export CORTEX_CODE_FRAMEWORK=arm,ansible. Supported frameworks: ARM, ANSIBLE, BICEP, CLOUDFORMATION, DOCKER, DOCKERFILE, HELM, KUBERNETES, KUSTOMIZE, OPENAPI, SCA, SECRETS, SERVERLESS, TERRAFORM, TERRAFORMJSON, TERRAFORMPLAN
--skip-framework $CORTEX_CODE_SKIP_FRAMEWORK	Skip specific frameworks. Example: --skip-framework terraform. Syntax: Use a single flag with comma-separated values for multiple frameworks. Both quoted ("arm,ansible") and unquoted (arm,ansible) formats are supported. Example: --skip-framework terraform, sca_package. Constraint: Do not use multiple skip --framework flags: --skip-framework terraform --skip-framework sca_package. Environment variables: export CORTEX_CODE_SKIP_FRAMEWORK="tf,sca"
--rule $CORTEX_CODE_RULE	Restrict the scan to specific check IDs; all other checks are skipped. Enter one or more comma-separated check IDs, for example --rule APPSEC_AWS_79,APPSEC_SECRET_80
--severity $CORTEX_CODE_SEVERITY	Filters scan results by severity level. Accepts one or more comma-separated values: unknown, low, medium, high, critical. Repeat the flag or use comma separation to specify multiple levels (for example, --severity high,critical). Constraint: Only effective when --upload-mode is set to no-upload. When upload mode is active, the flag is ignored and an informational message is displayed
--ignore-existing-secrets $CORTEX_CODE_IGNORE_EXISTING_SECRETS	In CI/CD scans, report only newly introduced secrets. This flag filters out secret findings whose fingerprints already exist in the Cortex Cloud findings backlog, which a periodic baseline scan populates. This flag is ignored during pull request scans
--blocked-only $CORTEX_CODE_BLOCKED_ONLY	Boolean flag. When set, shows only blocked findings in the output. Available only in upload mode
--summary-position $CORTEX_CODE_SUMMARY_POSITION	Sets the position for displaying the summary information relative to the findings. Values: top, bottom
--upload-mode $CORTEX_UPLOAD_MODE	Upload mode determines the method or mode used to upload data. See common flags for more information
--download-external-modules $CORTEX_CODE_DOWNLOAD_EXTERNAL_MODULES	(Optional, default False) Download external Terraform modules from public Git repositories and the Terraform Registry so they are included in the IaC scan. . Use --external-modules-download-path to control the download location (defaults to .external_modules). Requires outbound network access
--external-modules-download-path $CORTEX_CODE_EXTERNAL_MODULES_DOWNLOAD_PATH	Specifies the directory to download external modules to. Defaults to .external_modules
--external-checks-dir $CORTEX_CODE_EXTERNAL_CHECKS_DIR	Local directory containing custom Cortex Python (.py) checks. The directory must be a Python package. This flag is repeatable and cannot be used with --external-checks-git.
--external-checks-git $CORTEX_CODE_EXTERNAL_CHECKS_GIT	Git URL containing custom Cortex Python (.py) checks. Supports //subdir and ?ref=.... This flag cannot be used with --external-checks-dir.
--external-checks-public-key $CORTEX_CODE_EXTERNAL_CHECKS_PUBLIC_KEY	Path to a PEM-encoded ECDSA P-256 public key used to verify signatures for custom Cortex Python (.py) checks. When set, any tampered or unsigned file aborts the scan with exit code 2 before any check runs. When unset, verification is disabled for backward compatibility. See Workflow: Sign and verify custom checks.
--output $CORTEX_CODE_OUTPUT	Output format for reporting. Supported formats: cli, json, spdx, junitxml, sarif, cyclonedx, cyclonedx_json
--output-file-path $CORTEX_CODE_OUTPUT_FILE_PATH	Specifies the output path for the scan result file
--deep-analysis $CORTEX_CODE_DEEP_ANALYSIS	Enables or disables deep analysis of the Terraform plan and related files
--repo-root-for-plan-enrichment $CORTEX_CODE_REPO_ROOT_FOR_PLAN_ENRICHMENT	Enriches Terraform plan findings by mapping them to their original .tf files
--skip-path $CORTEX_CODE_SKIP_PATH	Specifies a path (file or directory) that should be skipped during the scanning process. This option is useful for excluding specific files or directories that are not relevant to the scanning analysis, increasing the efficiency and accuracy of scan results
--compact $CORTEX_CODE_COMPACT	Do not display code blocks in the output
--no-fail-on-crash $CORTEX_NO_FAIL_ON_CRASH	See common flags for a description
--validate-secrets CORTEX_APPSEC_VALIDATE_SECRETS	Validate detected secrets against their respective services to confirm they are active. By default, this feature is disabled. Set CORTEX_APPSEC_VALIDATE_SECRETS = true to enable it
--timeout $CORTEX_CODE_TIMEOUT	Sets the maximum time the Cortex CLI will wait for triggered local scan processes to complete. Default value: 15 minutes. Syntax: To specify a duration: Use a numeric value followed by a unit (for example --timeout 10m) Default unit: Numeric values entered without a unit are interpreted as seconds. For example, 30 is equal to 30 seconds. Supported units: Milliseconds, seconds, minutes and hours
--start-commit	Starting commit hash for git history scanning (Git Hook flag). No environment-variable equivalent is available.
--commit-list	Comma-separated list of commit hashes to scan (Git Hook flag). No environment-variable equivalent is available.
--hook-event	Git hook event type, such as pre-commit (Git Hook flag). No environment-variable equivalent is available.
--help	See common flags for a description

How to retrieve the repository ID

Option 1: From the local repository checkout (Recommended)

git config --get remote.origin.url

Remove any trailing .git and take the final two path segments. For example, [https://github.com/my-org/my-repo.git](https://github.com/my-org/my-repo.git) yields my-org/my-repo. This matches the exact logic the CLI uses to auto-derive the value.

Option 2: From the Cortex Cloud console

1. Navigate to Inventory → All Assets → Repositories.
2. Select the repository row to open the side card.
3. Copy the title displayed at the top of the side card (in owner/repo format).

Note: Two console fields are commonly mistaken for this value and neither is valid:

• Asset ID (in the side card Properties section) is an internal platform hash, not a repository path. Passing it will fail validation
• Repository Name (in the table column) is only the repository name without the owner

Option 3: From the Public API

GET /public_api/appsec/v1/repositories

In the response, locate your repository and join the owner and name fields with a forward slash (owner/name).

EXAMPLES

Explicitly defining the repository path and branch

Use this pattern for local scans or custom builds. It sets the repository and branch manually.

cortexcli code scan \
  --directory . \
  --branch main \
  --repo-id my-org/my-repo \
  --upload-mode upload

Providing --repo-id and --branch explicitly associates results with the correct platform asset. This works regardless of local Git status or API key permission levels.

Auto-deriving values from the local Git checkout

Use this minimal syntax from a developer workstation inside an active Git working tree.

# Auto-derive the repository path and branch from the local Git remote
cortexcli code scan \
  --directory . \
  --upload-mode upload

When omitted, the CLI derives --repo-id from the origin remote URL. It derives --branch from the local HEAD checkout. Auto-derivation requires an API key with write or upload permissions. With a read-only API key, pass both values explicitly.

Running in GitHub Actions workflows

Use native GitHub Actions context variables to set the repository and branch dynamically.

# In GitHub Actions workflows
cortexcli code scan \
  --directory . \
  --branch ${{ github.ref_name }} \
  --repo-id ${{ github.repository }} \
  --upload-mode upload

Always pass --repo-id and --branch explicitly in CI. GitHub Actions checkouts often use a detached HEAD. Auto-derivation can resolve the branch as HEAD, rather than the target branch.

Running in GitLab CI pipelines

Use predefined GitLab CI variables to populate the repository path and branch.

# In GitLab CI pipelines
cortexcli code scan \
  --directory . \
  --branch $CI_COMMIT_BRANCH \
  --repo-id $CI_PROJECT_PATH \
  --upload-mode upload

GitLab CI supports multi-segment subgroup paths, such as my-group/my-subgroup/my-repo. $CI_PROJECT_PATH provides the complete forward-slash-delimited path required by --repo-id.