README.md

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.

Issues · Security · Contributing · MCPShark

---

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
• Prerequisites
• Quick start
• Test AAuth Explorer with MCP Shark
• Cursor: one combined MCP server
• Repository layout
• OWASP-style coverage
• Other MCP clients
• Individual servers
• MCPShark static scan harness
• AAuth: in-app sample traffic
• One-go testbed
• AAuth end-to-end reference
• YARA Smart Scan and traffic
• Vulnerability themes
• References
• 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 (@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 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)
• 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

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

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

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

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. CLI, curl, Cursor JSON: 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

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	Combined vulnerable stdio server
servers/*.js	Category servers + AAuth HTTP fixtures + CLI harness stubs
fixtures/mcp-shark-cli.harness.json	Multi-server static scan harness (embedded tools)
mcp.json	Harness copy at repo root; npm run harness:copy-mcp-json overwrites it
fixtures/cursor-aauth-mcp.json	Optional Cursor entries for HTTP fixtures
scripts/	Cursor MCP config, AAuth runner/traffic, testbed
yara-rules/*.yar	ASI01–ASI10 YARA rules
.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:

{
  "mcpServers": {
    "security-test": {
      "command": "node",
      "args": ["/Users/you/src/mcp-shark-security-lab/servers/all-vulnerabilities-server.js"]
    }
  }
}

Individual servers

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

   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)

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

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 vs live graph from captured packets.

CLI checks:

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

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 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
• OWASP Top 10 for LLM Applications
• Model Context Protocol
• MCPShark

---

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. 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 when positioning changes.