NeuralTrust | Platform for Agent Security.

The TrustGuard Codex plugin uses Codex lifecycle hooks (not Codex External guardrails / Prisma AIRS) and POST /v1/evaluate. One org collector API key is shared across the company. Codex has no “import plugin from GitHub” marketplace flow like Cursor. You install from the repo (local) or IT deploys hooks + config (enterprise).

Console setup

Create a Codex collector (Catalog → IDE & coding agents).
Mint a tgk_… API key on the Auth tab (shown once — store it).
Assign a default policy on the Policies tab.

Local / pilot

git clone https://github.com/NeuralTrust/trustguard-codex-plugin.git
cd trustguard-codex-plugin
make build
make install-local

make install-local:

Builds trustguard-codex and installs it under ~/.trustguard/bin
Copies the plugin to ~/.codex/plugins/trustguard
Writes ~/.codex/hooks.json with absolute paths to the bootstrap scripts
(Codex runs hooks from the session cwd, so relative paths are unreliable)

Then write the API key config:

// ~/.trustguard/codex.json  (chmod 600)
{
  "data_url": "https://<your-trustguard-host>",
  "api_key": "tgk_…",
  "fail_mode": "closed"
}

In Codex run /hooks, trust the TrustGuard definitions, and send a test prompt.

Enterprise

IT deploys more than the API key file. Codex does not pull hooks from a marketplace; managed hooks must already exist on disk.

Piece	What to deploy
Hook bootstraps	`trustguard-hook.sh` / `.ps1` / `.cmd` from the repo under a fixed directory (e.g. `/Library/Application Support/TrustGuard/codex-hooks`)
Binary	Optional: put `trustguard-codex` on `PATH` or `~/.trustguard/bin`. If missing, the bootstrap downloads the pinned release from GitHub Releases (checksum-verified) on first use
API key config	MDM-managed `codex.json` (paths below)
Codex policy	`requirements.toml` (or MDM equivalent) so hooks stay on and point at those scripts

1. Managed API key config

{
  "data_url": "https://<your-trustguard-host>",
  "api_key": "tgk_…",
  "fail_mode": "closed",
  "transform_action": "deny"
}

OS	Managed config path
macOS	`/Library/Application Support/TrustGuard/codex.json`
Linux	`/etc/trustguard/codex.json`
Windows	`%ProgramData%\TrustGuard\codex.json`

When this file includes api_key, that key, data_url, and fail_mode are locked (user ~/.trustguard/codex.json and env cannot override them). Soft prefs (timeout_ms, transform_action, events, consumer_id) still layer from the user file.

2. Enforce hooks (`requirements.toml`)

Example (see the full file in the plugin repo):

[features]
hooks = true
allow_managed_hooks_only = true

[hooks]
managed_dir = "/Library/Application Support/TrustGuard/codex-hooks"
windows_managed_dir = 'C:\ProgramData\TrustGuard\codex-hooks'

[[hooks.UserPromptSubmit]]
[[hooks.UserPromptSubmit.hooks]]
type = "command"
command = '/Library/Application Support/TrustGuard/codex-hooks/trustguard-hook.sh'
timeout = 30
statusMessage = "TrustGuard evaluating prompt"

# Same command for PreToolUse and PostToolUse — see enterprise-requirements.toml

Source: docs/enterprise-requirements.toml in the plugin repo. Exact keys can vary by Codex version — confirm against Codex hooks docs. With allow_managed_hooks_only = true, developers cannot disable managed hooks from /hooks.

Verify

In Codex run /hooks and confirm TrustGuard hooks are listed (and managed under enterprise policy).
Send a test prompt.
Confirm the event in TrustGuard Activity (consumer_id is typically codex:<user> or codex:<email> when the payload includes email).

Smoke-test the binary (optional):

echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"},"session_id":"thr_1"}' \
  | trustguard-codex hook

What is evaluated

Codex event	TrustGuard protocol	Direction	Notes
`UserPromptSubmit`	`llm`	input	Block with `decision: "block"`
`PreToolUse` (`Bash` / `apply_patch`)	`all`	input	Deny with `permissionDecision: "deny"`
`PreToolUse` (MCP / other tools)	`mcp` tools/call	input	Same deny shape
`PostToolUse`	`mcp` result	output	`decision: "block"` replaces the tool result for the model

Attributes

attributes.collector.type = "ide"
attributes.codex.event, cwd, model, turn
consumer_id prefixed codex: (email from payload when present, else configured / OS fallback)

Introduction

Core concepts

Detector catalog

Integrations

Evaluate API

Codex

Console setup

Local / pilot

Enterprise

1. Managed API key config

2. Enforce hooks (`requirements.toml`)

Verify

What is evaluated

Attributes

​Console setup

​Local / pilot

​Enterprise

​1. Managed API key config

​2. Enforce hooks (requirements.toml)

​Verify

​What is evaluated

​Attributes

​Related

Console setup

Local / pilot

Enterprise

1. Managed API key config

2. Enforce hooks (`requirements.toml`)

Verify

What is evaluated

Attributes

Related