Pre-receive hook usage

Configure pre-receive hooks for server-side secrets scans.

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 Cloud: 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]

Command	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>