prismorsec/immunity-agent/immunity-agent

prismor: Runtime Security Skill

You are a coding agent. This skill keeps your tool calls safe: it blocks destructive shell commands, scores package installs against a live IOC feed, substitutes real secrets at execution time so they never enter model context, screens what tools return before it becomes your context, and audits every tool call to a local signed store.

This file is the decision tree. The pattern is: trigger → which command → how to recover if blocked. Detail lives in `docs/`; link out, don't duplicate.

When to invoke this skill

Trigger this skill (read the matching section below) the first time any of these happen in a session:

Outside these triggers, do nothing. Prismor runs as a hook and intercepts in the background. You don't need to wrap every tool call.

1. Check state (first command of every session)

Run one command. It replaces the old info + cloak status + status trio:

prismor status

Read the output line by line:

• `Hooks: not installed` → go to Setup. Without hooks, Prismor sees nothing.
• `Hooks: claude (observe, project; configured)` → monitoring is on but only logging. Fine for the first session in a new repo. Recommend the user switch to enforce when they're ready (see Setup).
• `Hooks: claude (enforce, project; configured)` → the hook configuration requests enforcement. It is followed by Note: agent invocation not verified; run prismor doctor for configuration checks: this line alone does not prove the agent invokes the hook. Read any Hook health: warnings.
• `Note:` lines → status reports its own misconfigurations: the same agent hooked at both project and global scope (every call screened twice), or the two scopes disagreeing on mode. These are the user's to fix, and the printed command is the fix. Relay it, don't run it.
• `Workspace:` → check this is the repo you're actually working in. A hook installed against a different workspace evaluates your calls under that repo's policy, which is a real misconfiguration worth raising.
• `Paused: yes` → enforcement is suspended (logging continues). Say so before relying on a clean run; a command that passes while paused may block when it resumes.
• `Cloaking: not installed` → secret-prevention layer is off. Only required if the user works with API keys / tokens through the agent. If they do, run prismor cloak install then register secrets per Safe-command map.
• `LATEST SESSION` shows findings → surface them to the user before starting new work.

Two follow-ups when the answer matters:

prismor mode show        # which governance posture this workspace runs, and any drift
prismor surfaces         # which enforcement surfaces are live, per agent on this host

If prismor is not on PATH, the workspace has never been set up. Go to Setup.

2. Setup (run once per workspace)

Setup is the user's command, not yours. prismor setup and prismor install-hooks write agent hook configs and Prismor's own policy, so the self-protection rules block an agent that runs them — including prismor install-hooks --help. Print the commands below and let the human run them.

Preferred path (works for every supported agent):

pip install prismor
prismor setup            # interactive setup TUI

Run from your shell (no TTY), a bare prismor setup installs nothing and prints the wizard's questions with the flags for each answer. Put those questions to the user and run the --non-interactive command they choose.

The wizard is four steps in observe mode. Choosing enforce inserts a governance mode step — three named postures, each shown with its coverage and friction — and only if the user picks custom does it fall through to the rule-by-rule picker. It also offers to serve built-ins over the mirror for agents where that's the recommended surface.

prismor setup also drops this skill into <workspace>/.claude/skills/immunity-agent/ so it travels with the project — that's where this file came from if you're reading it locally. Re-running setup, or prismor update (which refreshes every registered workspace), replaces a copy that still matches what setup installed, along with the ## Security (Prismor) block it writes into CLAUDE.md / AGENTS.md (between prismor:security markers). A copy you edited is kept; one from an older release, which predates that check, is replaced, with the old file saved as SKILL.md.bak. prismor docs <page> always prints the docs from the installed version.

Non-interactive / CI / piped:

pip install prismor
prismor install-hooks --agent claude --mode observe --workspace .
# switch to enforce when the user is ready:
prismor install-hooks --agent claude --mode enforce --workspace .
# apply a whole posture instead of hand-picking rules:
prismor mode apply dev-safe

Multi-agent workspace (Claude + Cursor + Windsurf in the same repo):

prismor install-hooks --agent all --mode enforce --workspace .

Per-agent matrix (only one --agent value per invocation, or all):

Agents with no hook protocol at all (n8n, hosted bots, closed CLIs) go behind the LLM proxy. Hosted agents that clone the repo onto their own VM (Claude Code on the web, Codex cloud, Copilot coding agent) use a committed install-hooks --portable config — see `docs/cloud-agents.md`. Full matrix, including partial and rules-only agents: `AGENT_INTEGRATIONS.md`.

After install, re-run prismor status. The Hooks: line lists configured agents; it does not prove the client loaded or executed them. prismor doctor passively checks hook configuration and recognized launchers for missing interpreters or dispatcher files, alongside policy, remote-policy signature, enrollment, telemetry sink, and chain state. prismor doctor --self-test opts into import and synthetic Claude-protocol allow/block probes through recognized generated dispatchers, using disposable state. This checks the shared dispatcher, not each client's protocol, actual invocation, or active workspace policy. Modified/custom/portable launchers and registered plugins remain unverified. --json exits non-zero on failure.

Production framework agents are a separate surface from coding-agent hooks. If the workspace is a Python/JS app that builds agents rather than a repo an agent edits, wrap the framework instead of installing hooks:

These adapters ship inside the prismor package — no separate install. Defaults differ between adapters (some observe, some enforce), so pass the mode explicitly and confirm a block in a test before relying on it. Adapters screen tool calls and redact tool results. Wrap each request in use_subject("user:alice") so a multi-tenant agent gets per-user attribution, IAM profiles, and suspension.

Keep current. prismor --version prints the running version, and prismor status adds a note: prismor X is available line when a newer release is out. If the user asks to upgrade, or you see that note, run:

prismor update            # self-update to the latest published release
prismor update --check    # check only, don't install