Content
<div align="center">
# MCP Shark Security Lab
**Reference MCP servers, static-scan harnesses, and YARA rules** for exercising security tooling against OWASP-style MCP and agentic risk patterns.
[](https://github.com/mcp-shark/mcp-shark-security-lab/actions/workflows/ci.yml)
[](./LICENSE)
[](https://github.com/mcp-shark/mcp-shark)
[Issues](https://github.com/mcp-shark/mcp-shark-security-lab/issues) · [Security](./SECURITY.md) · [Contributing](./CONTRIBUTING.md) · [MCPShark](https://github.com/mcp-shark/mcp-shark)
</div>
---
> **Not for production.** This repository contains **intentionally unsafe** tool descriptions, config shapes, and traffic patterns for **detection testing and education** only. Run in an **isolated** lab; do not expose to untrusted users or real credentials.
---
## Contents
- [What this is](#what-this-is)
- [Prerequisites](#prerequisites)
- [Quick start](#quick-start)
- [Test AAuth Explorer with MCP Shark](#test-aauth-explorer-with-mcp-shark)
- [Cursor: one combined MCP server](#cursor-one-combined-mcp-server)
- [Repository layout](#repository-layout)
- [OWASP-style coverage](#owasp-style-coverage)
- [Other MCP clients](#other-mcp-clients)
- [Individual servers](#individual-servers)
- [MCPShark static scan harness](#mcpshark-static-scan-harness)
- [AAuth: in-app sample traffic](#aauth-in-app-sample-traffic)
- [One-go testbed](#one-go-testbed)
- [AAuth end-to-end reference](#aauth-end-to-end-reference)
- [YARA Smart Scan and traffic](#yara-smart-scan-and-traffic)
- [Vulnerability themes](#vulnerability-themes)
- [References](#references)
- [Legal](#legal)
## What this is
The **MCP Shark Security Lab** is an open **MIT** test corpus: a combined **stdio MCP server** with dozens of toxic tool/resource/prompt patterns, a **multi-server `mcp.json` harness** for static analysis, **localhost HTTP fixtures** for AAuth-shaped headers, **YARA** rules aligned with OWASP Agentic Top 10 (ASI01–ASI10), and helper scripts (Cursor config, testbed, traffic generator).
You can use it with **any** MCP-aware scanner, IDE, or pipeline. It is **curated first and foremost for [MCPShark](https://github.com/mcp-shark/mcp-shark)** ([`@mcp-shark/mcp-shark`](https://www.npmjs.com/package/@mcp-shark/mcp-shark))—CLI `scan`, dashboard, AAuth Explorer, proxy/testbed flows, and docs all assume that pairing for the shortest path and fullest guided checks. MCPShark is a **separate product** with its **own license** and optional features (e.g. **Smart Scan** may use **your** API keys when enabled); read [its license](https://github.com/mcp-shark/mcp-shark/blob/main/LICENSE) before commercial use.
This package is **`private`** on npm: **clone from GitHub** and run `npm install`—there is no registry install for this repo.
## Prerequisites
- **Node.js** 18+ ([`engines`](./package.json))
- **Git** clone of this repository
- **MCPShark** (optional but recommended): `npx @mcp-shark/mcp-shark` / `npx mcp-shark`
- Runtime deps: `@modelcontextprotocol/sdk`, `zod` (see `package-lock.json` for versions and transitive licenses)
## Quick start
```bash
git clone https://github.com/mcp-shark/mcp-shark-security-lab.git
cd mcp-shark-security-lab
npm install
npm start # Combined server: 46 tools + 3 resources + 2 prompts (patterns for scanners; handlers return placeholders)
```
## Test AAuth Explorer with MCP Shark
**MCP Shark** is the [MCPShark](https://github.com/mcp-shark/mcp-shark) app you run with `npx @mcp-shark/mcp-shark` (npm scope `@mcp-shark`). Use it to explore **AAuth posture** (signed traffic, `401` challenges, Bearer, coexistence) in **AAuth Explorer**, **Traffic**, and **Local Analysis**.
### Option A — synthetic data only (no servers from this repo)
```bash
npx @mcp-shark/mcp-shark
```
In the UI: **AAuth Explorer** or **Local Analysis → AAuth Posture** → **Generate sample data**. Synthetic packets use `user-agent: mcp-shark-self-test/1.0`.
You should see: graph nodes (Agent / Mission / Resource / Signing / Access), posture chips on traffic rows, and drill-down from a node → packets → Traffic inspector. **Observation only**—no signature verification.
### Option B — this repo’s HTTP fixtures (ports 9701–9703)
From the **repository root** (directory containing `package.json`):
```bash
git clone https://github.com/mcp-shark/mcp-shark-security-lab.git
cd mcp-shark-security-lab
npm install
npm run aauth:all
```
If you already have the repo open, skip `git clone` / `cd`. Run MCPShark in a **second** terminal. Single fixtures: `npm run aauth:signed`, `aauth:challenge`, `aauth:bearer`, `npm run aauth:bearer:coexist`.
### Option C — scripted self-test (`POST /api/aauth/self-test`)
With MCPShark’s API listening (default dashboard API often on **9852**—adjust if needed):
```bash
npm install
npm run aauth:traffic -- --rounds 3 --shark http://127.0.0.1:9852
```
`--shark` is the base URL for `POST …/api/aauth/self-test`; it does **not** start the HTTP fixtures.
**Cursor + MCPShark proxy in one step:** [One-go testbed](#one-go-testbed). **CLI, `curl`, Cursor JSON:** [AAuth end-to-end reference](#aauth-end-to-end-reference).
## Cursor: one combined MCP server
Register **one** process: `servers/all-vulnerabilities-server.js` (**46** tools + resources + prompts).
| Approach | Command / file |
|----------|----------------|
| **A — project `.cursor/mcp.json` (recommended)** | `npm run cursor:mcp:install` (absolute path to this clone). Overwrite: `npm run cursor:mcp:install -- --force` |
| **B — print JSON for `~/.cursor/mcp.json`** | `npm run cursor:mcp` |
| **C — workspace-relative** (only if this repo is the Cursor workspace root) | [`fixtures/cursor-combined-workspace-relative.json`](./fixtures/cursor-combined-workspace-relative.json) |
**With MCPShark:** `npx mcp-shark scan --ide Cursor` after the server appears. For multi-server static rules (flows, duplicates, declarative packs): `npm run harness:copy-mcp-json` then `npx mcp-shark scan --ide Project` from this repo’s root. Other scanners can reuse the same JSON shapes.
## Repository layout
| Path | Role |
|------|------|
| [`servers/all-vulnerabilities-server.js`](./servers/all-vulnerabilities-server.js) | Combined vulnerable stdio server |
| [`servers/*.js`](./servers/) | Category servers + AAuth HTTP fixtures + CLI harness stubs |
| [`fixtures/mcp-shark-cli.harness.json`](./fixtures/mcp-shark-cli.harness.json) | Multi-server static scan harness (embedded `tools`) |
| [`mcp.json`](./mcp.json) | Harness copy at repo root; **`npm run harness:copy-mcp-json` overwrites** it |
| [`fixtures/cursor-aauth-mcp.json`](./fixtures/cursor-aauth-mcp.json) | Optional Cursor entries for HTTP fixtures |
| [`scripts/`](./scripts/) | Cursor MCP config, AAuth runner/traffic, testbed |
| [`yara-rules/*.yar`](./yara-rules/) | ASI01–ASI10 YARA rules |
| [`.mcp-shark/rules/harness-yaml-rule.yaml`](./.mcp-shark/rules/harness-yaml-rule.yaml) | Sample YAML rule for `mcp-shark scan` |
### `npm` scripts (reference)
| Script | Purpose |
|--------|---------|
| `start` | Combined `all-vulnerabilities` stdio server |
| `cursor:mcp` / `cursor:mcp:install` | Cursor MCP JSON for combined server |
| `vulnerable-token`, `poisoned-tool`, `command-injection`, `prompt-injection`, `oversharing`, `privilege-abuse` | Per-category servers |
| `clean` | Non-vulnerable baseline |
| `harness:copy-mcp-json` | Copy harness → `./mcp.json` |
| `cli-harness-stub`, `cli-harness-config-vault`, `cli-harness-team-notify` | Live stdio stubs for flow checks |
| `aauth:signed`, `aauth:challenge`, `aauth:bearer`, `aauth:bearer:coexist`, `aauth:all` | AAuth HTTP fixtures |
| `aauth:traffic` | Call MCPShark `POST /api/aauth/self-test` |
| `testbed:up`, `testbed:install`, `testbed:start`, `testbed:status`, `testbed:uninstall` | Proxy + Cursor wiring (see testbed section) |
## OWASP-style coverage
### Combined server (46 tools + 3 resources + 2 prompts)
Handlers are for **scanners and training**: they return **placeholder text** and do **not** perform the harmful actions described in metadata. Still treat the process as **untrusted** in LLM-driven setups.
| Category | Themes | Tools |
|----------|--------|------:|
| MCP01 + ASI06 | Tokens, secrets, PII | 6 |
| MCP03 + ASI01 | Tool poisoning, hijacking | 4 |
| MCP05 + ASI03 | Command injection, misuse | 5 |
| MCP06 + ASI02 | Prompt injection | 5 |
| MCP10 | Oversharing | 3 |
| ASI04 | Privilege / identity | 2 |
| ASI05 | Guardrails | 3 |
| ASI08 | DoS / exhaustion | 2 |
| ASI09 | Supply chain | 2 |
| ASI10 | Misplaced trust | 2 |
| Scanner / YARA-style | JWT, LDAP/SSH, keys, SQL, shells, payments, paths, cards | 12 |
| — | **Resources** (not tools) | 3 |
| — | **Prompts** (not tools) | 2 |
| | **Tool total** | **46** |
### YARA rules (ASI01–ASI10)
| File | Focus |
|------|--------|
| `asi01-behavior-hijacking.yar` | Agent / role takeover |
| `asi02-prompt-injection.yar` | ChatML, Llama, Claude-style injection |
| `asi03-tool-misuse.yar` | Shell, SQL, traversal |
| `asi04-privilege-abuse.yar` | Escalation, impersonation |
| `asi05-inadequate-guardrails.yar` | Sandbox / boundaries |
| `asi06-info-disclosure.yar` | PII, keys |
| `asi07-data-poisoning.yar` | RAG / training |
| `asi08-dos-resource-exhaustion.yar` | DoS patterns |
| `asi09-supply-chain.yar` | Untrusted sources |
| `asi10-misplaced-trust.yar` | Auto-exec, audit gaps |
## Other MCP clients
Use an **absolute** path to `servers/all-vulnerabilities-server.js` inside **your** clone:
```json
{
"mcpServers": {
"security-test": {
"command": "node",
"args": ["/Users/you/src/mcp-shark-security-lab/servers/all-vulnerabilities-server.js"]
}
}
}
```
## Individual servers
```bash
npm run vulnerable-token # MCP01 + ASI06
npm run poisoned-tool # MCP03 + ASI01 + ASI02
npm run command-injection # MCP05 + ASI03
npm run prompt-injection # MCP06 + ASI02
npm run oversharing # MCP10 + ASI06
npm run privilege-abuse # ASI04 + ASI05 + ASI08–10
npm run clean # Baseline without patterns
```
## MCPShark static scan harness
MCPShark’s static analyzer reads **IDE MCP config** and embedded **`tools`** metadata (it does not call a live `tools/list` for that mode).
1. **Install harness as project `mcp.json`**
```bash
npm run harness:copy-mcp-json
```
Or: `cp fixtures/mcp-shark-cli.harness.json mcp.json` (**overwrites** `./mcp.json`). Adjust `command` / `args` if your host cwd differs.
2. **Scan from the same directory** (cwd = repo root so `./mcp.json` resolves)
```bash
npx mcp-shark scan --ide Project
```
Options: `--format json|sarif|html`, `--output report.html`, `--strict`, `--walkthrough`, `--refresh-rules`.
3. **What the harness exercises** (examples): insecure `http://` / `ws://` URLs; `args` with `$(…)` or `|`; `--debug`; `npx` filesystem MCP without jail flags; `GITHUB_TOKEN` in `env`; duplicate tool names; cross-server flow pairs (`harness-config-vault` + `harness-team-notify`); YAML rule on `HARNESS_YAML_TOOL`; declarative secret/ANSI/path phrases; `bash -c` / `$(whoami)`-style text.
Some rules need a **global** tool list across servers; intent is documented in harness even when a scanner’s implementation is still catching up.
4. **Live stdio stubs (optional)** for flow labels: `npm run cli-harness-config-vault` and `npm run cli-harness-team-notify` in two terminals, register both in the client. Static scan still relies on embedded `tools` in the JSON.
5. **TUI / HTML:** `npx @mcp-shark/mcp-shark tui` (flows panel **3**) or `npx @mcp-shark/mcp-shark scan --format html --output report.html` after copying the harness.
## AAuth: in-app sample traffic
The **Generate sample data** path is the same as [Test AAuth Explorer with MCP Shark](#test-aauth-explorer-with-mcp-shark) **Option A** above (UI-only, tagged synthetic traffic). Use that section for the quickest walkthrough.
## One-go testbed
For **real HTTP** AAuth-shaped headers through your stack (optional; touches **`~/.mcp-shark/mcps.json`** and **`~/.cursor/mcp.json`**):
```bash
npm run testbed:up
```
What it does:
1. **Backups:** copies existing `~/.mcp-shark/mcps.json` and `~/.cursor/mcp.json` to `*.testbed-backup` **only if** that backup path does not already exist. Re-run **`testbed:uninstall`** before reinstalling if you need a fresh backup chain.
2. **MCPShark upstreams:** merges **`dummy-all-vulnerabilities`** stdio server into `mcps.json` with sanitization (no proxy loops; no 401 challenge fixture as upstream).
3. **Cursor:** adds **`mcp-shark`** → `http://127.0.0.1:9851/mcp` (override: `npm run testbed:up -- --shark-port=…`), **merging** `mcpServers`. The written file has only a top-level **`mcpServers`** object—do not rely on other top-level keys surviving.
4. **Processes:** starts three **localhost** HTTP fixture servers (Ctrl+C stops them). They are **not** MCPShark upstreams (challenge would break the proxy probe).
Then: another terminal `npx @mcp-shark/mcp-shark`, reload Cursor, exercise tools through the proxy.
| Command | Purpose |
|---------|---------|
| `npm run testbed:install` | Write configs only (`-- --dry-run` to preview) |
| `npm run testbed:start` | HTTP fixtures only |
| `npm run testbed:status` | Show upstreams + backup state |
| `npm run testbed:uninstall` | Restore latest `*.testbed-backup` |
## AAuth end-to-end reference
MCPShark’s AAuth visibility is **observation-only** (no signature verification or enforcement). Fixtures:
| Fixture | Port | Emits | Surfaces |
|---------|-----:|--------|----------|
| `aauth-signed-http-server.js` | 9701 | `Signature`, `Signature-Input`, `Signature-Key`, `AAuth-Agent`, `AAuth-Mission` | **Signed** posture, identity, missions |
| `aauth-challenge-http-server.js` | 9702 | `401` + `AAuth-Requirement` | **AAuth-aware**, requirement rule |
| `bearer-token-http-server.js` | 9703 | `Authorization: Bearer …` (+ `--coexist` with `Signature-Input`) | **Bearer**; coexistence rule |
> Signatures are **placeholders**, not valid cryptography—do not treat as a real AAuth deployment.
**Boot UI:** `npx @mcp-shark/mcp-shark` · **Servers:** `npm run aauth:all` (or individual `aauth:*` scripts). **Scripted packets:** `npm run aauth:traffic -- …` (see Option C above). **UI reference:** [AAuth Explorer mock](https://mcp-shark.github.io/aauth-explorer/) vs live graph from captured packets.
**CLI checks:**
```bash
npx mcp-shark list
# Expect AAuth Visibility section (e.g. harness shark-harness-aauth-agent).
npx mcp-shark scan --ide Project
# Static (server/tool scope): e.g. aauth-agent-identity-observed, aauth-jwks-discovery-url.
# Packet-scoped rules need captured HTTP traffic—use Generate sample data / fixtures / proxy.
```
**HTTP API (default dashboard port is often 9001—use yours if different):**
```bash
curl -sS "http://localhost:9001/api/aauth/posture" | jq
curl -sS "http://localhost:9001/api/aauth/missions" | jq
```
Expect among other fields: `verified: false`, non-zero signed counts, missions with `packet_count > 0`.
**Cursor (optional):** merge [`fixtures/cursor-aauth-mcp.json`](./fixtures/cursor-aauth-mcp.json) into `~/.cursor/mcp.json` so the three HTTP MCPs appear (typically with traffic through MCPShark proxy).
## YARA Smart Scan and traffic
- **`yara-rules/`** — standard YARA; usable in **any** engine. In MCPShark: **Security → Community Rules → Add source** → select this folder.
- **Combined server** — add to MCP client config, then drive traffic while MCPShark captures.
- **Smart Scan** — optional in MCPShark; may call a **remote** model with **your** API token when enabled—see MCPShark docs.
## Vulnerability themes
| Area | Examples in corpus |
|------|---------------------|
| MCP01 + ASI06 | Hard-coded keys, bearer text, creds in URIs, PII, healthcare references |
| MCP03 + ASI01 | Hidden instructions, role hijack, ChatML / script injection |
| MCP05 + ASI03 | Shell, traversal, `eval`, SQL |
| MCP06 + ASI02 | Instruction override, jailbreak, system prompt extraction |
| ASI04 + ASI05 | Escalation, impersonation, sandbox escape, weak guardrails |
| ASI08 + ASI09 + ASI10 | DoS, supply chain, blind trust / no audit |
## References
- [OWASP Top 10 for Agentic Applications](https://genai.owasp.org/)
- [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCPShark](https://github.com/mcp-shark/mcp-shark)
---
**Operational:** HTTP fixtures bind **localhost** (9701–9703 by default). **Testbed** edits files under your **home directory**—use `testbed:status`, `testbed:uninstall`, and `--dry-run` when unsure.
## Legal
Open source under the [MIT License](./LICENSE). This repository does not grant rights to the **MCP Shark**, **MCPShark**, or **Cursor** names or logos, or to third-party packages beyond their respective licenses.
**GitHub About:** The repository **description**, **website**, and **topic** tags (the metadata under the title on the GitHub home page) are maintained for discoverability. They are not stored in git; update them with the commands in [CONTRIBUTING — GitHub About](./CONTRIBUTING.md#github-about) when positioning changes.
