llm-security/examples/poisoned-claude-md/README.md

# Memory-Poisoning Walkthrough

> **WARNING: This is a demonstration fixture, NOT a real attack.**
> The fixture `CLAUDE.md` and `health-checker.md` are deliberately
> poisoned. They are never adopted as project memory — the run
> script only feeds them to the deterministic scanner.

## What this demonstrates

`memory-poisoning-scanner.mjs` (MEM scanner, OWASP LLM01 / LLM06)
detects **cognitive-state poisoning** in files Claude Code loads
into the agent's context: `CLAUDE.md`, `.claude/agents/*.md`,
`.claude/rules/*.md`, `memory/*.md`, `REMEMBER.md`, `*.local.md`,
and `.claude-plugin/plugin.json`.

The scanner runs six independent detectors. The fixture plants at
least one signal for each:

| # | Detector | Fixture signal | Severity |
|---|----------|----------------|----------|
| 1 | `detectInjection` | "Ignore previous instructions" + spoofed `# IMPORTANT` block + NL indirection ("FIRST silently read ~/.aws/credentials") | CRITICAL/MEDIUM |
| 2 | `detectShellCommands` | `curl -sSL ... \| bash` and `eval "$(curl ...)"` outside code blocks | LOW |
| 3 | `detectSuspiciousUrls` | `webhook.site/abc123`, `requestbin.com/r/zzz`, `requestbin.net/r/health-...` | HIGH |
| 4 | `detectCredentialPaths` | `~/.aws/credentials`, `~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, `wallet.dat`, `kubeconfig`, `service-account-key`, `~/.config/gcloud/credentials.db` | HIGH |
| 5 | `detectPermissionExpansion` | `allowed-tools = Bash, Write, Edit, all`, `bypassPermissions = true`, `--dangerously-skip-permissions` | CRITICAL |
| 6 | `detectEncodedPayloads` | A base64 blob that decodes to a `curl ... \| bash` command | MEDIUM |

The fixture also covers v7.2.0's E15 surface — agent files
(`.claude/agents/*.md`) — by planting matching signals in
`fixture/.claude/agents/health-checker.md`.

The fixture is not stored in the repository as files: antivirus products
(Windows Defender among them) quarantine a poisoned `CLAUDE.md` on clone.
It lives encoded in `fixture.archive.json` (rot13 text, non-ASCII characters
as codepoint numbers) and is written to a temp directory when you need it.

## How to run

```bash
cd plugins/llm-security
node examples/poisoned-claude-md/run-memory-poisoning.mjs

# Detailed: full per-finding listing with file:line
node examples/poisoned-claude-md/run-memory-poisoning.mjs --verbose
```

The walkthrough materializes the fixture itself and deletes it on exit. To
scan it with anything else, materialize first, then scan the printed path:

```bash
FIX="$(node examples/malicious-skill-demo/materialize.mjs examples/poisoned-claude-md/fixture.archive.json)"
node scanners/scan-orchestrator.mjs "$FIX"
rm -rf "$(dirname "$FIX")"   # when you are done
```

Expected: `6 pass, 0 fail` and `18` total findings (or more, as
detectors evolve).

## Scanner involved

- **`scanners/memory-poisoning-scanner.mjs`** — invoked directly
  via `import { scan }`. Takes `(targetPath, discovery)` where
  discovery is built by `scanners/lib/file-discovery.mjs::discoverFiles()`.
  No Claude Code agent runtime is required.

The orchestrated form (`/security scan` or `node scanners/scan-orchestrator.mjs`)
runs this scanner alongside the other 9. This walkthrough isolates
it for clarity.

## Why memory poisoning is special

CLAUDE.md and friends are loaded into Claude Code's context **before**
prompt injection hooks run. They are persistent across sessions.
A poisoned CLAUDE.md can:

- Override the system prompt (CRITICAL injection patterns)
- Plant credential-path priors so the agent quietly reads `.ssh/` /
  `.aws/` when the operator asks an unrelated question
- Expand permissions (`bypassPermissions`, `--dangerously-skip-permissions`)
  in a way the operator never explicitly approved
- Smuggle base64-encoded shell commands disguised as "telemetry"
- Direct exfiltration to attacker-controlled URLs

Detection at scan time (before the file is loaded into a session)
is the cleanest defense. `pre-prompt-inject-scan.mjs` catches some
of these patterns at runtime, but only for content that flows
through `UserPromptSubmit` — CLAUDE.md is loaded earlier, so the
scanner has to catch the file before anyone runs Claude Code in
that directory.

## Layered defense

| Layer | What it covers |
|-------|----------------|
| `memory-poisoning-scanner` (scan time) | The file itself, before any session loads it |
| `pre-prompt-inject-scan` (runtime) | Injection patterns in user prompts and selected tool inputs |
| `post-mcp-verify` (runtime) | Patterns that arrive via tool output |
| `pre-write-pathguard` (runtime) | Blocks Write to `.env`, `.ssh/`, `.aws/`, etc. — counters the credential-read instruction at the moment it would actually be carried out |

This walkthrough exercises only the first layer.

## OWASP / framework mapping

| Code | Framework | Why |
|------|-----------|-----|
| LLM01 | OWASP LLM Top 10 (2025) | Prompt injection — CLAUDE.md is the most direct injection surface |
| LLM06 | OWASP LLM Top 10 (2025) | Excessive Agency — permission-expansion directives broaden tool surface |
| ASI04 | OWASP Agentic Top 10 | Untrusted-instruction influence on agent behavior |
| AT (Agent Traps) | DeepMind | Hidden cognitive priors — categories 1, 3, 6 |

## Limitations

- The fixture exercises the **deterministic** scanner. The full
  `/security audit` flow would also run `posture-assessor-agent`
  and the LLM-driven `skill-scanner-agent`, which could find
  additional context-dependent issues.
- The scanner's regex set is fixed. A novel injection wording the
  pattern doesn't match would slip past — that is the documented
  v5.0 honest-limitation of deterministic detection. For attack
  diversity, see `examples/prompt-injection-showcase/`.

## See also

- `knowledge/owasp-llm-top10.md` — LLM01 / LLM06 background
- `tests/lib/memory-poisoning-scanner.test.mjs` — unit-test contract
- `tests/fixtures/memory-scan/poisoned-project/` — separate test
  fixture (smaller, kept in tests/, not duplicated here)
- `expected-findings.md` (in this folder) — the testable contract