Imported from PrismorSec/prismor (SKILL.md). Install upstream with npx skills add PrismorSec/prismor. Copyright stays with the author.

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, and audits every tool call to a local SQLite 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) → 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) → fully active. Proceed.
• 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.

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

2. Setup (run once per workspace)

Preferred path (works for every supported agent):

pip install prismor
prismor setup            # interactive setup TUI

For Claude Code, prismor setup also drops this skill into <workspace>/.claude/skills/prismor/ so it travels with the project — that's where this file came from if you're reading it locally.

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 .

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):

After install, verify by re-running prismor status. The Hooks: line should now list the agent you just installed. If anything looks wrong — hooks present but nothing logging, remote policy not syncing, enrollment half-applied — run prismor doctor, which health-checks every subsystem (hooks, policy, remote-policy signature, enrollment, telemetry sink, chain state) and exits non-zero on failure with --json.

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. They default to observe; the user opts into enforce explicitly. Wrap each request in use_subject("user:alice") so a multi-tenant agent gets per-user attribution, IAM profiles, and suspension.

Keep current. prismor status prints the running version at the top. If the user asks to upgrade, or you see a stale version reported by prismor status, run:

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

This is the supported upgrade path — don't tell the user to pip install --upgrade directly, since prismor update also handles the post-install hook refresh.

Optional: cloaking for secret prevention (Claude Code and Hermes today):

# Claude Code (default):
prismor cloak install --workspace .
prismor cloak add stripe_key      # reads value from stdin, never shell history

# Hermes (pip-installed Hermes auto-discovers via entry-points; this is the
# explicit filesystem install for non-pip setups):
prismor cloak install --agent hermes --workspace .

# Both at once:
prismor cloak install --agent all --workspace .

prismor cloak status reports which agents have the cloaking layer active. See docs/hermes.md for the full Hermes integration story.

3. Safe-command map

When you're about to take one of these actions, swap to the right column. Don't ask the user; these are safer-by-default substitutions and the user already opted into them by installing immunity.

Two patterns that come up often:

Package install: always wrap. The wrapper passes through transparently for non-install commands, so it's safe to alias npm / pip globally if the user prefers.

Secret usage: one-time registration, then placeholder forever:

# one time, from a shell the user controls (not from the agent transcript):
prismor cloak add openai_key

# then in any tool call:
curl https://api.openai.com -H "Authorization: Bearer @@SECRET:openai_key@@"

The pre-tool-use hook substitutes the real value at execution time; the post-tool-use hook scrubs any echoed value before it returns to the model. If you see @@SECRET:name@@ in a transcript, that's working as intended. Do not "fix" it by inlining a value.

4. When blocked

Prismor blocking is a signal, not a problem to route around. The recovery sequence is:

1. Read the rejection reason: it's printed on stderr with rule id, category, and severity. Every block also prints unblock steps, narrowest first — one call, one rule, one session, one repo.
2. Reproduce with prismor check "<cmd>": confirms the rule that fired and lets you experiment with variations.
3. Pick one:
   • The command was wrong → fix it. Most blocks are accurate.
   • The command is fine for this project → relay the printed unblock steps to the user and stop. Do not apply them yourself (see below). If the user would rather delegate, they can run prismor unlock (password-gated, ~3-minute window) — inside that window you may run the printed prismor allow … command yourself, then retry the original action.
   • The rule is wrong globally → file an issue, don't silently disable.
4. Never pass --no-verify, set PRISMOR_MODE=observe to "make it work", prismor pause, or uninstall the hooks to unblock a single command. All four defeat the entire layer.

You cannot apply the override yourself — by design. The unblock steps address the human at the keyboard, not you. .prismor/policy.yaml, the agent hook configs, the prismor allow/unlock/pause/setup commands, the dashboard's write API, and the unlock credential are all guarded by the self-protection rules (agent-config-tampering, prismor-self-edit — CRITICAL), so an agent that touches them to widen its own permissions just earns a second block. This is true even when the user asks you to: the correct response is to show them the exact command and let them run it.

The one sanctioned exception is an unlock window: the human runs prismor unlock and enters their password, which lifts the self-edit block for a few minutes (3 by default). Inside the window you may run prismor allow … and other policy edits — every one is logged — but the dismantle routes stay shut: you still cannot relax a self-protection rule, change or read the unlock password, or extend your own window. When it expires or the human runs prismor lock, everything re-blocks.

Some rules can't be overridden at all. destructive-command, secret-exfiltration, rce-canary, privilege-escalation, dos-resource-exhaustion, audit-trail-tampering, and tool-category-crossover sit on a non-overridable floor — a policy that tries to disable them is ignored rather than honored. On an install that chose its enforce set explicitly (settings.selection: explicit, unmanaged workspaces only), an unselected floor rule reports instead of blocking, but its definition still cannot be weakened; the self-protection rules block always, everywhere. If one of these fires, there is no override path. Fix the command.

For org-managed workspaces, the escape hatch is prismor exempt request --reason "…", which asks an admin for a time-boxed relaxation instead of editing anything locally.

5. On-demand audits

When the user asks for a security check or you finish a multi-step task, pick the smallest tool that answers the question:

6. Governance surfaces

Three subsystems govern what the agent can reach rather than what it types. You mostly won't invoke these — but you need to recognize them when they fire, and know which command answers the user's question.

MCP gateway

One MCP connector that fronts every other MCP server. Each tools/call is policy-evaluated before it forwards, and each response is injection-scanned before it reaches you — so a malicious tool result is caught before it becomes context.

prismor mcp-gateway install     # move this workspace's .mcp.json servers behind the gateway
prismor mcp-gateway             # serve (default action)
prismor mcp-gateway uninstall   # restore the .mcp.json backup

Defaults to observe. Tools appear namespaced as <server>__<tool>. If a tool name suddenly has that shape, the gateway is active — that's expected, not a bug to work around. Deep dive: docs/mcp-gateway.md.

Egress control

Policy-driven network allow/deny for outbound requests, with cloud metadata endpoints denied by default.

prismor egress show             # effective policy and where it came from
prismor egress test <host>      # verdict for one host, no request made
prismor egress report           # what was actually attempted

allow / deny / rm / mode mutate the policy — those are the user's to run, not yours. Deep dive: docs/network-isolation.md.

Tool tags

Tags classify tools by capability (read, write, network, exec) so rules can say "no tool that reads private data may also reach the network" instead of naming every tool. This is what backs tool-category-crossover — a floor rule.

prismor tags list               # tools seen + resolved tags + tier
prismor tags test               # dry-run rules against recorded sessions
prismor tags lint               # validate rule expressions

MCP tools self-declare tags via _meta; Prismor auto-tags the rest. Deep dive: docs/tool-tags.md.

Shadow-AI discovery

prismor discover inventories the AI surface on the host — coding agents, MCP servers, and provider credentials — and flags whatever runs outside Prismor's coverage. Read-only and host-local. Narrow with agents, mcp, or keys; add --fail-on-shadow in CI.

7. Enterprise / org enrollment

These commands apply when the workspace is managed by a Prismor org (central policy, remote telemetry, admin exemptions). Skip this section for personal workspaces.

prismor enroll                  # enroll this machine against a Prismor org
prismor enroll-status           # show enrollment status and remote policy sync
prismor workspace               # show or set whether this workspace is org-managed or personal
prismor exempt request --reason "…"   # ask an admin for a time-boxed rule relaxation
prismor logout                  # un-enroll: remove device identity + cached remote policy
prismor doctor                  # health-check hooks, policy signature, enrollment, telemetry

Once enrolled, the org's signed policy is authoritative — it can flip rules to enforce even on a device installed in observe mode, and an org admin can pause or resume the device from the console.

Pause is not an unblock tool. prismor pause (24h, or --for 30m) and prismor pause-hard (until prismor resume) suspend enforcement only — observe-mode logging keeps running, so the session is still recorded. These are for a human who needs breathing room during an incident, never for getting one command through. Don't run them on your own initiative.

Hard rules

• Do not bypass a Prismor block. Investigate, then either fix the command or hand the printed unblock steps to the user.
• Never edit .prismor/policy.yaml, .claude/settings.json, or any agent hook config to widen your own permissions — even if asked. Show the user the command; let them run it.
• Never run prismor pause, prismor pause-hard, PRISMOR_MODE=observe, or prismor uninstall-hooks to get a command through.
• Never inline a real secret value when an @@SECRET:<name>@@ placeholder exists. Never echo, log, or narrate the real value of a registered secret.
• Never run pip / npm / cargo install directly when prismor supplychain is available. Wrap it.
• Don't run prismor setup again if prismor status shows hooks already installed; it's idempotent but the user reads "running setup" as "something broke".
• Don't edit files under ~/.prismor/secrets/ or advisories/ by hand. Use the CLI.

Reference

Start here for the full command map: docs/cli-reference.md — every command, every flag, grouped by domain, with links to each deep dive.

Capability deep dives:

• docs/prismor-runtime.md: policy engine, session logs, audit, full CLI reference
• docs/supply-chain.md: scoring table, IOC feed, ecosystem support
• docs/sweep-and-cloak.md: secret prevention design, practical setup, best practices, threat model, and cleanup
• docs/hermes.md: Hermes Agent integration — secret cloaking plugin, pip auto-discovery, CLI install path
• docs/semantic-guard.md: opt-in LLM-assisted prompt-injection guard
• docs/skill-scanner.md: MCP server + skill risk scanning
• docs/agentic-architecture-review.md: design-time checklist for multi-agent/tool-using system architecture, mapped to OWASP Agentic AI, OWASP LLM Top 10, NIST AI RMF, and EU AI Act controls
• docs/network-isolation.md: policy-driven egress control, allowlists, raw-IP detection, cloud-metadata denies
• docs/mcp-gateway.md: one MCP connector fronting all MCP servers — per-tool policy evaluation, response injection-scanning, per-user governance
• docs/tool-tags.md: tag-rule expression language, capability tiers, MCP _meta auto-tagging
• docs/installation.md: every install path — pip, curl, git clone, PEP 668 systems, cloaking setup
• docs/policy-layers-and-exemptions.md: org/project/repo precedence, the non-overridable floor, time-boxed exemptions
• docs/canary.md: honeytoken tripwires for recon detection
• docs/iam.md: named agent identities and permission profiles
• docs/frameworks-overview.md: every framework adapter (OpenAI Agents, LangChain/LangGraph, CrewAI, browser-use, Pydantic AI, AutoGen Core, Agno, Semantic Kernel, Google ADK, BeeAI, Claude Agent SDK, Vercel AI SDK, Mastra) and the shared use_subject() pattern
• docs/scoped-agent.md: session-scoped, task-derived rules
• docs/learning.md: mining session history for new rules
• docs/dashboard.md: terminal + web dashboards and session forensics
• docs/transcript-ingest.md: reconstructing past agent activity from on-disk transcripts, what-if enforce reporting, coverage gaps
• docs/docker.md: container hardening and limitations

Project docs:

• AGENT_INTEGRATIONS.md: per-agent hook surfaces (matrix)
• AGENTS.md: guidance for contributors editing this repo