Pre-receive hook usage - Administrator Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM 3.x Documentation
Product
Cortex XSIAM
Creation date
2025-07-15
Last date published
2026-06-11
Category
Administrator Guide

The hook executes a script on every git push.

By default, Cortex CLI pre-receive hooks:

  • Only scans code changes: It analyzes the code difference included in the pushed commits, not the entire repository

  • Scans for secrets only: The analysis is focused on detecting sensitive information

  • Does not upload results to Cortex XSIAM: All scan results are kept local to your machine (on the server)

Understanding the script variables

  • CORTEX_CLI: Defines the executable path, pointing to the absolute location of the cortexcli binary

  • BASE_COMMAND: Assembles the core command string, including authentication flags (--api-base-url, --api-key-id, --api-key) and the primary command: code pre-receive. The use of ${...} ensures authentication variables are injected as flag values

  • OPTIONAL_FLAGS: An empty variable placeholder for adding optional runtime arguments

Command flag reference

Use the following flags with the pre-receive command to customize scanner behavior.

Example command structure:

$ cortexcli code pre-receive [options]

Option

Description

--ignore-existing-secrets

Ignores secrets that already exist in the periodic scan (default: false) [$CORTEX_CODE_IGNORE_EXISTING_SECRETS]

--validate-secrets

Checks if the secrets are valid (default: false) [$CORTEX_CODE_VALIDATE_SECRETS]

--skip-path

Specifies a file or directory path to skip during the scan [$CORTEX_CODE_SKIP_PATH]

--compact

Prevents the display of code blocks in the output (default: false) [$CORTEX_CODE_COMPACT]

--summary-position

Determines whether the summary appears on top (before the check results) or on bottom (after the check results). (default: top) [$CORTEX_CODE_SUMMARY_POSITION]

--no-fail-on-crash

Returns exit code 0 instead of 2 in case of a failure in the integration with the platform (default: false) [$CORTEX_CODE_NO_FAIL_ON_CRASH]

--help, -h

Displays a help message with available options

Breakglass: Bypassing the hook

The breakglass feature allows you to intentionally bypass the pre-receive hook security scan. This is useful in urgent situations where a push must go through immediately, but it should be used with caution as it overrides your security policies.

  1. Configure your server to accept custom push options:

    ```bash
git config receive.advertisePushOptions true
```

  2. Add the -o breakglass option to your git push command:

    ```bash
git push -o breakglass
```
Troubleshooting and recommendations

  • Refer to the Cortex CLI for more information on the Cortex CLI.

  • Modify the script as required based on the server running the VCS

  • The Cortex CLI must be available on the server. This documentation does not describe the CLI installation process

  • Update the Cortex CLI periodically

  • Instead of adding the API URL and credentials directly in the script, consider creating a ~/.cortexcli/.cortex.yaml configuration file (owned by the git user and group) with the following contents:

    CORTEX_API_BASE_URL: <api base url>
CORTEX_API_KEY: <api key>
CORTEX_API_KEY_ID: <api key id>