Let your agent setup Prismor

---
name: setup-prismor
description: >
  Install and configure the Prismor security stack on a developer machine — both
  the `prismor` CLI (pip-installable scanner for GitHub repos) and the
  `immunity-agent` runtime guard (the Warden hook layer that watches AI coding
  agents in real time). Use this skill when the user says "set up prismor",
  "install prismor", "install immunity agent", "install warden", "set up
  prismor on my machine", "onboard a new machine to prismor", or asks how to
  install either of these tools. Walks through prerequisites, both installs,
  API-key wiring, optional cloak (secret-prevention) layer, mode selection
  (observe vs enforce), and post-install verification.
---

# Set Up Prismor Locally (CLI + Immunity Agent)

You are installing the Prismor security stack on this machine. There are two
distinct components and the user almost always wants both:

| Component | What it is | How it installs |
|---|---|---|
| **prismor CLI** (`prismor-cli`) | Python package that scans GitHub repos for vulns, secrets, and generates SBOMs by calling `api.prismor.dev`. | `pip install prismor` + `PRISMOR_API_KEY` env var |
| **Immunity Agent** (`prismor` / Warden) | Local runtime monitor that hooks Claude Code / Cursor / Windsurf, blocks dangerous tool calls, and optionally substitutes secrets at execution time (Cloak). | `git clone` → `~/.prismor` then `bash ~/.prismor/scripts/init.sh <project>` |

The two are independent. You can install just one, but most users want both:
the CLI for CI/repo scans, Warden for live protection while coding with an AI
agent.

---

## TL;DR — Impatient Mode

```bash
# 1. Prereqs
brew install python git jq            # macOS — adjust for Linux

# 2. Prismor CLI
python3 -m pip install --upgrade prismor
echo 'export PRISMOR_API_KEY="<paste-from-prismor.dev>"' >> ~/.zshrc
source ~/.zshrc
prismor --version

# 3. Immunity Agent (Warden) — start in observe mode in your project
pip3 install pyyaml
git clone https://github.com/PrismorSec/prismor.git ~/.prismor
PRISMOR_MODE=observe bash ~/.prismor/scripts/init.sh "$(pwd)"

# 4. Optional dashboard
python3 ~/.prismor/warden/cli.py serve   # http://127.0.0.1:7070
```

---

## Operating Rules (for the agent driving the install)

### 1. Confirm scope before touching anything

Use `AskUserQuestion` once at the start to nail down:

1. **Which components?** — `Both` (default) / `CLI only` / `Immunity Agent only`
2. **Warden mode** — `observe` (log only, recommended for first run) / `enforce` (actually block).
3. **Enable Cloak (secret prevention)?** — `yes` / `no` (default no). Only applies if Immunity Agent is selected and Claude Code is the target agent. Requires `jq` on PATH.
4. **Target workspace for Warden hooks** — default is the current working directory. Confirm before installing project-scoped hooks anywhere else.

Do not assume answers. Cloak in particular touches secret storage under `~/.prismor/secrets/` and should never be enabled without an explicit yes.

### 2. Verify prerequisites first, install second

Before running anything destructive, check the prereqs in parallel:

- `python3 --version` (need ≥ 3.7 for CLI; the init script also requires python3)
- `pip3 --version` or `python3 -m pip --version`
- `git --version`
- `python3 -c "import yaml"` — PyYAML is a hard requirement for the Warden policy engine; the init script aborts without it.
- `command -v jq` — only if Cloak is being enabled.

If any are missing, stop and tell the user which one to install (Homebrew commands for macOS, `apt-get`/`dnf` for Linux). Do not try to install system packages without consent.

### 3. CLI install — pip, then API key

```bash
pip install --upgrade prismor
prismor --version          # verify
```

Then wire the API key. The CLI reads `PRISMOR_API_KEY` from the environment. **Never** echo the key into a file write or persist it to chat history. Ask the user to paste it themselves, then append the export to the right shell rc file:

- zsh (default on macOS): `~/.zshrc`
- bash: `~/.bashrc` (or `~/.bash_profile` on macOS)
- fish: `~/.config/fish/config.fish` (`set -gx PRISMOR_API_KEY …`)

Confirm with `prismor config` (which prints the resolved configuration without leaking the key value).

### 4. Immunity Agent install — clone, then init

```bash
# Clone (or pull) the runtime monitor
git clone https://github.com/PrismorSec/prismor.git ~/.prismor
# Or, if ~/.prismor already exists:
git -C ~/.prismor pull --quiet

# Initialize hooks for the current project
PRISMOR_MODE=<observe|enforce> PRISMOR_CLOAK=<0|1> \
  bash ~/.prismor/scripts/init.sh <TARGET_DIR>
```

Notes that bite people:

- `init.sh` has an **interactive TUI** that takes over the terminal if stdin is a real TTY (it `exec`s into `scripts/setup.py`). When you run it via the `Bash` tool, stdin is *not* a TTY, so it falls through to the non-interactive path — which is what we want. Pass the env vars on the command line so the install is fully scripted.
- The init script auto-detects which agents to install hooks for by looking for `.claude/`, `.cursor/`, `.windsurf/` in the target dir and in `$HOME`. If none are found it defaults to Claude Code.
- It also creates or appends to `CLAUDE.md` in the target directory with a pointer to `security-playbook`. If the user does not want this, install the hooks directly with `python3 ~/.prismor/warden/cli.py install-hooks` and skip `init.sh`.

### 5. Post-install verification

Run these and surface the results to the user:

```bash
prismor --version
prismor config
python3 ~/.prismor/warden/cli.py --help
python3 ~/.prismor/warden/cli.py install-hooks --help   # confirms install
```

Optionally offer to start the dashboard:

```bash
python3 ~/.prismor/warden/cli.py serve   # http://127.0.0.1:7070
```

If the dashboard is started, run it in the background and tell the user the URL — do not block the session waiting on it.

### 6. Cloak (only if explicitly opted in)

Cloak stores real secret values under `~/.prismor/secrets/` and substitutes them at execution time when the agent references `@@SECRET:<name>@@`. Install with:

```bash
PRISMOR_CLOAK=1 bash ~/.prismor/scripts/init.sh <TARGET_DIR>
```

Then register secrets **interactively** — the user pastes the value, never you:

```bash
warden cloak add <name>      # prompts for the value
warden cloak list            # shows registered names (never values)
warden cloak status          # confirms hook install
```

Treat any cloak-related code, file, or output as security-sensitive: never print, log, or narrate a real secret value, even if it appears in command output. Use the `@@SECRET:<name>@@` placeholder form in all examples.

### 7. Mode selection guidance

If the user is unsure between `observe` and `enforce`, recommend `observe` for the first 24–48 hours so they can review what would have been blocked via the dashboard before flipping the switch. Promote to `enforce` by re-running `init.sh` with `PRISMOR_MODE=enforce`.

### 8. What this skill does NOT do

- Does not push, commit, or open PRs.
- Does not run `prismor --fix` or any scanning command on the user's repos without an explicit ask — installation only.
- Does not install Homebrew, Python, or any system-level dependency without the user agreeing to the exact command.
- Does not enable `enforce` mode silently. If the user picked `observe`, leave it on `observe`.

---

## Detailed Playbook

### 0. Prerequisites

Required for both pieces:

- **Python ≥ 3.7** (`python3 --version`)
- **pip** (`python3 -m pip --version`) — comes with Python on macOS and most Linux distros
- **git** (`git --version`)

Required for Immunity Agent specifically:

- **PyYAML** — `pip3 install pyyaml`. The Warden policy engine refuses to load without it; `init.sh` aborts with a clear error.
- **jq** *(only if you want Cloak)* — `brew install jq` / `apt-get install jq`. The cloaking hooks shell out to `jq` to rewrite tool arguments.

### 1. Install the Prismor CLI

```bash
python3 -m pip install --upgrade prismor
prismor --version
```

If you get `command not found`, your Python user-script directory isn't on `PATH`. Find it and add it:

```bash
python3 -m site --user-base
# e.g. /Users/you/Library/Python/3.11
# add /Users/you/Library/Python/3.11/bin to PATH in ~/.zshrc
```

Set the API key (get one at https://prismor.dev):

```bash
# Permanent (zsh — default on macOS)
echo 'export PRISMOR_API_KEY="your-key-here"' >> ~/.zshrc
source ~/.zshrc
```

First scan (smoke test):

```bash
prismor --repo facebook/react --scan --quiet
```

Commands worth knowing:

| Command | What it does |
|---|---|
| `prismor --repo <r> --scan` | Vulnerability scan |
| `prismor --repo <r> --sbom` | Generate Software Bill of Materials |
| `prismor --repo <r> --detect-secret` | Secret detection |
| `prismor --repo <r> --fullscan` | All three above |
| `prismor --repo <r> --scan --fix` | Scan, then open a PR with AI-generated fixes |
| `prismor start-scan <r>` | Kick off an async scan, returns a job ID |
| `prismor scan-status <job_id>` | Check an async scan's progress |
| `prismor trigger-fix <r>` | Standalone fix run |
| `prismor fix-status <job_id>` | Check a fix run's progress |
| `prismor repos` | List repos visible to your account |
| `prismor config` | Print resolved config |

### 2. Install the Immunity Agent (Warden)

```bash
pip3 install pyyaml                                            # hard requirement
git clone https://github.com/PrismorSec/prismor.git ~/.prismor
PRISMOR_MODE=observe PRISMOR_CLOAK=0 \
  bash ~/.prismor/scripts/init.sh "$(pwd)"
```

Environment variables:

| Var | Values | Default | Effect |
|---|---|---|---|
| `PRISMOR_MODE` | `observe` / `enforce` | `observe` | `observe` logs would-be blocks but lets them through. `enforce` actually blocks. |
| `PRISMOR_CLOAK` | `1` / `0` | `0` | Install the secret-cloaking hook layer. Requires `jq` and a Claude Code workspace. |
| `PRISMOR_HOME` | path | `~/.prismor` | Where the Warden repo lives. |

What `init.sh` actually does:

1. Verifies `python3` and PyYAML are present.
2. Clones or pulls Warden into `~/.prismor`.
3. Auto-detects which AI agent(s) you use in this workspace (`.claude/`, `.cursor/`, `.windsurf/`).
4. Writes or appends a `## Security (Prismor)` section to `CLAUDE.md` in the target dir, pointing the agent at the `security-playbook`.
5. Calls `python3 ~/.prismor/warden/cli.py install-hooks` for each detected agent, registering the workspace and writing hook entries into the agent's settings file (e.g. `.claude/settings.json`).
6. If `PRISMOR_CLOAK=1`, calls `warden cloak install` to add the pre/post-tool-use hooks that substitute `@@SECRET:<name>@@` placeholders.
7. Verifies the threat-feed signature against `~/.prismor/keys/public.pub`.

### 3. Dashboard (optional)

```bash
python3 ~/.prismor/warden/cli.py serve            # http://127.0.0.1:7070
python3 ~/.prismor/warden/cli.py serve --port 8080
```

### 4. Updates

```bash
# Prismor CLI
python3 -m pip install --upgrade prismor

# Immunity Agent
git -C ~/.prismor pull
```

### 5. Uninstall

```bash
# Prismor CLI
python3 -m pip uninstall prismor

# Immunity Agent — per-workspace hook removal
python3 ~/.prismor/warden/cli.py uninstall-hooks --workspace "$(pwd)" --agent claude

# Optionally: cloak hooks and secrets
python3 ~/.prismor/warden/cli.py cloak uninstall

# Full removal
rm -rf ~/.prismor
```

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `PyYAML is not installed` | `pip3 install pyyaml`, then re-run `init.sh`. |
| `PRISMOR_CLOAK=1 set but jq is missing` | `brew install jq` (macOS) or `apt-get install jq` (Debian), re-run with `PRISMOR_CLOAK=1`. |
| `prismor: command not found` after pip install | Add `$(python3 -m site --user-base)/bin` to `PATH`. |
| `PRISMOR_API_KEY environment variable is not set` | The export is in the rc file but the current shell hasn't sourced it. Open a new terminal or `source ~/.zshrc`. |
| Hooks not firing in Claude Code | Re-run `python3 ~/.prismor/warden/cli.py install-hooks --workspace . --agent claude` to rewrite settings. |
| Private repo scan fails | Visit prismor.dev → Settings → Integrations and connect GitHub. The CLI uses the backend's stored credential, not a local `GITHUB_TOKEN`. |
| Dashboard shows empty | You haven't run any agent session in a registered workspace yet. Use Claude Code in a workspace where you've run `install-hooks`. |
| Feed signature verification failed | `git -C ~/.prismor pull` to refresh, then `bash ~/.prismor/scripts/verify_feed.sh`. |

---

## References

- Prismor CLI repo: https://github.com/PrismorSec/prismor-cli
- Immunity Agent repo: https://github.com/PrismorSec/prismor
- Security playbook: https://github.com/PrismorSec/security-playbook
- Dashboard: https://prismor.dev
- Docs: https://docs.prismor.dev