Installation

Prerequisites

• Node.js 18+ (native fetch, crypto.randomUUID)
• Codex CLI with hooks support (hooks are enabled by default in current versions)
• Prisma AIRS API key (x-pan-token)
• AIRS security profile configured in Strata Cloud Manager

Install

npm (recommended)

npm install -g @cdot65/prisma-airs-codex-hooks

This installs the CLI globally and makes the prisma-airs-codex-hooks command available system-wide.

Requires a published release

This package is not yet published to npm (v0.1.0 pending release), so this command currently returns a 404 — use the From source tab until the first release lands.

From source

git clone https://github.com/cdot65/prisma-airs-codex-hooks.git
cd prisma-airs-codex-hooks
corepack enable   # provides the pinned pnpm 10
pnpm install
pnpm build

Environment Variables

Add to your shell profile (~/.zshrc, ~/.bashrc, or ~/.zsh.d/):

export PRISMA_AIRS_API_KEY=<your-x-pan-token>                         # required
export PRISMA_AIRS_PROFILE_NAME="Codex CLI - Hooks"                    # recommended
export PRISMA_AIRS_API_ENDPOINT=https://service.api.aisecurity.paloaltonetworks.com  # optional

Only PRISMA_AIRS_API_KEY is required

The endpoint defaults to the US region. PRISMA_AIRS_PROFILE_NAME sets the AIRS security profile for all scan directions. If you need different profiles per direction, use PRISMA_AIRS_PROMPT_PROFILE, PRISMA_AIRS_RESPONSE_PROFILE, and PRISMA_AIRS_TOOL_PROFILE as overrides.

Regional Endpoints

Region	Endpoint
US (default)	https://service.api.aisecurity.paloaltonetworks.com
EU	https://service-de.api.aisecurity.paloaltonetworks.com
India	https://service-in.api.aisecurity.paloaltonetworks.com
Singapore	https://service-sg.api.aisecurity.paloaltonetworks.com

Validate Connectivity

npm global install

prisma-airs-codex-hooks validate-connection
prisma-airs-codex-hooks validate-detection

From source

pnpm validate-connection
pnpm validate-detection

Register Hooks in Codex

npm global install

prisma-airs-codex-hooks install --global

From source

pnpm install-hooks --global

This copies the self-contained hook bundles (*.mjs) and airs-config.json into ~/.codex/hooks/, then writes the hook registrations to ~/.codex/hooks.json. Hook commands embed the absolute node binary (process.execPath at install time) — Codex runs hooks with a system PATH, so a bare node from nvm/asdf would fail with exit 127. The bundles themselves have no repository or node_modules dependency. After switching node versions, re-run the installer and re-trust via /hooks.

Without --global, the installer targets the current repository instead: bundles go to <git-root>/.codex/hooks/ and registrations to <git-root>/.codex/hooks.json, with commands resolved via $(git rev-parse --show-toplevel) so hooks work when Codex starts from a subdirectory.

Global installation recommended

Use --global to install hooks at ~/.codex/hooks.json so they apply across all sessions without per-project setup. Project-level hooks only load when the project's .codex layer is trusted.

Trust the Hooks in Codex

Codex requires you to review and trust non-managed hooks before they run:

1. Open Codex and run /hooks.
2. Review the Prisma AIRS hook definitions and trust them.

Trust is hash-based

Codex records trust against each hook definition's hash. Re-running the installer after any change to the hook commands marks them for review again — re-trust via /hooks.

Older Codex versions

Hooks are enabled by default in current Codex. Older versions need this in ~/.codex/config.toml:

[features]
hooks = true

(codex_hooks still works as a deprecated alias.)

Verify

npm global install

prisma-airs-codex-hooks verify --global

From source

pnpm verify-hooks --global

Uninstall

npm global install

prisma-airs-codex-hooks uninstall --global

From source

pnpm uninstall-hooks --global

Removes AIRS entries from hooks.json while preserving other hooks. Hook bundles, config, and logs under .codex/hooks/ are left in place.