@darkhunt-security/endpoint-codex 0.9.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "darkhunt-guard",
+  "version": "0.9.0",
+  "hooks": "./hooks/hooks.json",
+  "description": "Darkhunt endpoint plugin for Codex CLI \u2014 full session trace capture and PreToolUse guardrails.",
+  "author": {
+    "name": "Darkhunt Limited",
+    "email": "support@darkhunt.ai"
+  },
+  "homepage": "https://github.com/darkhunt-security/endpoint-plugins"
+}

package/README.md

@@ -0,0 +1,76 @@
+# Darkhunt Guard — Codex CLI
+
+Full session trace capture and PreToolUse guardrails for [Codex CLI](https://github.com/openai/codex).
+
+Capture is on by default. **Enforcement ships off** and is enabled per rule.
+
+## Install
+
+```
+/plugin marketplace add darkhunt-security/darkhunt-telemetry-ts
+/plugin install darkhunt-guard@darkhunt
+/darkhunt-guard:setup
+```
+
+`/darkhunt-guard:setup` needs one thing — a Darkhunt API key — and it will not ask you to
+paste it into the agent. It picks up the key `darkhunt-cli enroll` already stored, or
+`DARKHUNT_API_KEY` from your shell, and discovers the tenant, workspace and application
+from it. Then it shows you where sessions will be sent, so you can confirm before
+anything ships.
+
+Capture starts on your **next** Codex CLI session — hooks are loaded when a session
+starts.
+
+## What it captures
+
+The session transcript, mapped to spans: user and assistant messages, thinking blocks,
+tool calls paired with their results, token usage, attachment metadata (never the bytes),
+and the subagent topology as linked child traces.
+
+Reading the transcript rather than instrumenting the agent is what makes this complete:
+there is no code path in Codex CLI we could have missed.
+
+## What it enforces
+
+A `PreToolUse` hook evaluates each tool call against a policy bundle before it runs, and
+can allow, deny, ask, or rewrite the input.
+
+Two rules constrain it, both deliberate:
+
+- **Bash and command-string rules are advisory** — they are recorded, never blocking.
+  Matching a shell string is bypassable, so blocking on it would offer a guarantee it
+  cannot keep.
+- **The guard fails closed.** If policy cannot be evaluated, the call is denied. An
+  install that has never been configured is not a failure and is allowed — there is no
+  policy to bypass yet.
+
+## Commands
+
+|                          |                                                                    |
+| ------------------------ | ------------------------------------------------------------------ |
+| `/darkhunt-guard:setup`  | Connect this machine. Re-runnable; shows current state first.      |
+| `/darkhunt-guard:status` | Is capture actually working? Routing, hook activity, shipping lag. |
+
+Both lanes fail silently by design — correct for the agent, unhelpful for whoever
+operates it — so `status` is where the truth lives.
+
+## Privacy
+
+Session content leaves your machine and is sent to the Darkhunt tenant you enrolled
+against. `status` prints that destination; read it before you rely on it.
+
+Hooks never touch the network. Shipping happens in a detached forwarder off a local
+spool, so nothing in the capture lane can block or slow a tool call.
+
+## Configuration
+
+`~/.darkhunt/endpoint-config.json`, mode `0600`, written by setup. One file for every
+endpoint, with per-endpoint overrides under `endpoints.<vendor>`.
+
+Turn everything off with `"enabled": false`. Turn off capture but keep enforcement with
+`"capture": { "enabled": false }`.
+
+---
+
+[github.com/darkhunt-security/endpoint-plugins](https://github.com/darkhunt-security/endpoint-plugins)
+· support@darkhunt.ai

package/commands/setup.md

@@ -0,0 +1,72 @@
+---
+description: Connect this machine to Darkhunt — capture Codex CLI sessions and enforce policy
+allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/enroll.mjs:*), Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs:*)
+---
+
+Set up the Darkhunt endpoint plugin on this machine.
+
+Current state:
+
+!`${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs 2>&1 || true`
+
+## The one hard rule
+
+**Never ask the user for their API key, and never accept one in this conversation.**
+
+A Darkhunt API key is an unscoped tenant credential. Anything in this session is sent to
+the model provider, written to the transcript on disk, kept in context for every later
+turn, and handed to subagents — and this plugin then ships that transcript to Darkhunt,
+so a key pasted here ends up in the captured trace data too. Enrollment finds the key
+itself, or the user runs one command in their own terminal. There is no third option,
+and no amount of user insistence makes pasting it here correct.
+
+## What to do
+
+**If the status above printed a profile, tenant and workspace**, this machine is already
+enrolled. Show the tenant, workspace, application and endpoint, and ask whether they want
+to re-enroll against a different one. Do not re-run enrollment unless they say yes.
+
+**Otherwise**, run:
+
+```
+${CLAUDE_PLUGIN_ROOT}/dist/bin/enroll.mjs
+```
+
+It looks for a key in `$DARKHUNT_API_KEY`, then in the credentials `darkhunt-cli enroll`
+wrote. Then react to the exit code:
+
+- **Exit 0** — done. Show the user exactly what it printed: endpoint, tenant, workspace,
+  application, and which key it used. Ask them to confirm this is where they expect their
+  sessions to go. This matters — a config routing to the wrong tenant looks identical to
+  a correct one from everywhere else, and this summary is the only place the mistake is
+  visible.
+
+- **Exit 3 — no key.** Do **not** ask for one. Tell the user to run this in their own
+  terminal, outside this session:
+
+  ```
+  darkhunt-cli enroll --api-key <key>
+  ```
+
+  Their key is in the dashboard under **Settings → Security → API Keys**. Once that
+  succeeds, run the enroll command above again — it will pick the key up. If they do not
+  have `darkhunt-cli`, they can instead `export DARKHUNT_API_KEY=<key>` in the shell they
+  launched Codex CLI from, and restart the session.
+
+- **Exit 2 — a choice is needed.** The key reaches more than one tenant, workspace or
+  application, and the options are listed. Show them by name, ask which one, then re-run
+  adding the chosen id — `--tenantId=`, `--workspaceId=` or `--applicationId=` — keeping
+  any already resolved. Repeat until it succeeds; there can be up to three rounds.
+
+- **Any other exit** — show the error. Do not retry with different arguments hoping it
+  passes.
+
+Finally, tell them capture begins on their **next** Codex CLI session, because hooks
+are loaded when a session starts, and that `/darkhunt-guard:status` shows whether it is
+working.
+
+## Also
+
+- Do not edit `~/.darkhunt/endpoint-config.json` by hand — enrollment writes it at 0600,
+  and a file with looser permissions is refused at load.
+- Enforcement ships **off**. Setup does not turn it on, and you should not offer to.

package/commands/status.md

@@ -0,0 +1,31 @@
+---
+description: Is Darkhunt capture actually working? Shows routing, hook activity and shipping lag
+allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs:*)
+---
+
+!`${CLAUDE_PLUGIN_ROOT}/dist/bin/status.mjs 2>&1 || true`
+
+Explain the output above to the user in a few lines. Both lanes fail silently by
+design — that is correct for the agent and unhelpful for whoever has to operate it — so
+this command is the only place the truth is visible.
+
+What the fields mean, and what to say:
+
+- **`cannot read ...endpoint-config.json`** — not set up yet. Tell them to run
+  `/darkhunt-guard:setup`. Nothing is being captured, and nothing is being blocked.
+- **tenant / workspace / application** — where sessions are being sent. Worth reading
+  aloud: a wrong destination looks exactly like a right one everywhere else.
+- **user … [from agent]** — traces are attributed to the signed-in Codex CLI account.
+  `[from config]` means a value someone typed in, which on a shared machine is likely to
+  be the wrong person.
+- **WARNING: session hooks are not firing** — the guard is running but
+  SessionStart/Stop/SessionEnd have gone quiet, so capture is riding PreToolUse alone.
+  Sessions are still captured, but anything before the last hook may be missing; suggest
+  a backfill if the gap looks large.
+- **total lag** — bytes written but not yet shipped. A small number that returns to zero
+  is normal. A number that only grows means the forwarder is not running, or every
+  export is being rejected — check `last pass` to tell those apart.
+- **last pass FAILED** — read out the cause. Checkpoints are held on failure, so nothing
+  has been lost; it will re-ship once the cause is fixed.
+
+Do not run anything else, and do not offer to change the configuration unless asked.