@mcp-shark/mcp-shark 1.6.0 → 1.7.2

package/README.md

@@ -4,21 +4,71 @@
 
   <h1>mcp-shark</h1>
 
- <p><strong>Security scanner for AI agent tools</strong> — static analysis on MCP configs and tool metadata on your machine (findings, toxic-flow heuristics, CI-friendly outputs). Use the <strong>local HTTP proxy</strong> and <strong>monitoring UI</strong> to aggregate IDE traffic to multiple MCP servers and inspect requests and responses in one place.</p>
-  <p><strong>Privacy:</strong> static scans need no cloud and send no telemetry. Refreshing rule catalogs is opt-in HTTPS (<code>update-rules</code>).</p>
+  <div style="text-align: left; max-width: 42rem; margin: 0 auto;">
+    <p><strong>Security scanner for AI agent tools</strong> — built for security and platform engineers working with MCP in the IDE.</p>
+    <p>Run a local static <code>scan</code> over MCP <strong>IDE configs</strong> and embedded tool metadata: <strong>41 rules</strong> (including <strong>AAuth visibility</strong>), toxic-flow heuristics, and <strong>SARIF</strong> / <strong>HTML</strong> / <strong>JSON</strong> reports. There is no hosted config-scan backend.</p>
+    <p>Add an optional <strong>local HTTP proxy</strong> with an <strong>in-browser dashboard</strong> so live traffic, findings, AAuth signals, and playground checks stay in one place—without sending your configs to a vendor.</p>
+    <p><strong>You can</strong></p>
+    <ul style="margin: 0.35rem 0 0.75rem; padding-left: 1.25rem;">
+      <li>Use <strong>Traffic</strong> for live JSON-RPC capture, filters, export, and AAuth posture chips</li>
+      <li>Run <strong>Local Analysis</strong> for OWASP-style findings over captured traffic</li>
+      <li>Run <strong>YARA Detection</strong> for traffic pattern rules (native engine when installed, regex fallback otherwise)</li>
+      <li>Open <strong>AAuth Explorer</strong> for a graph of agents, missions, resources, and signing / access signals</li>
+      <li>Use <strong>MCP Playground</strong> to call tools, prompts, and resources through the proxy</li>
+      <li>Optionally run <strong>Smart Scan</strong> (AI-backed; uses <strong>your</strong> API token when enabled)</li>
+      <li>Use <strong>Server setup</strong> to detect configs, convert format, and route the editor through the proxy</li>
+    </ul>
+    <p><strong>Privacy:</strong> static scans need no cloud and send no telemetry. Refreshing rule catalogs is opt-in HTTPS (<code>update-rules</code>).</p>
+  </div>
 
   [![npm version](https://img.shields.io/npm/v/@mcp-shark/mcp-shark.svg)](https://www.npmjs.com/package/@mcp-shark/mcp-shark)
   [![License: Non-Commercial](https://img.shields.io/badge/License-Non--Commercial-red.svg)](LICENSE)
 
 </div>
 
----
+## Dashboard at a glance
 
-```bash
-npx @mcp-shark/mcp-shark
-```
+These captures are from the live **dashboard** with **real captured traffic** (dummy MCP or your own upstreams). Start with `npx @mcp-shark/mcp-shark serve --open`. **Smart Scan** is not shown below — it depends on an optional remote API token. **MCP Playground** appears once you have at least one MCP upstream configured (the Playground capture uses a demo server with tools loaded).
 
-![mcp-shark demo](docs/assets/demo.gif)
+### Live traffic capture
+
+Every JSON-RPC frame between your IDE and each MCP upstream is captured with full headers, body, timing, and an AAuth posture chip. Filter by method, status, server, session, AAuth agent / mission / posture.
+
+![Traffic Capture](docs/assets/hero-traffic.png)
+
+### MCP Playground
+
+Pick an upstream, load **tools**, **prompts**, and **resources** from that server, then call tools or read resources through the proxy — useful for validating behavior before it hits your IDE. The view below shows the tools list for a configured demo MCP.
+
+![MCP Playground](docs/assets/playground.png)
+
+### AAuth Explorer
+
+Force-directed knowledge graph of every Agent / Mission / Resource / Signing algorithm / Access mode observed across captured traffic. Use **Generate sample data** for a quick demo graph, or capture real AAuth-shaped traffic through the proxy.
+
+![AAuth Explorer](docs/assets/aauth-explorer.png)
+
+### Local Analysis
+
+Offline rule-based scanner over captured traffic. The **AAuth Posture** card summarizes signed / aauth-aware / bearer / no-auth distribution; the **Toxic flows (proxy traffic)** panel infers cross-server pairings from observed `tools/list` responses. With packets already in the database, use **Replay from DB** (when no live MCP is attached) and then **Analyse** to populate findings — the view below is after that run.
+
+![Local Analysis](docs/assets/local-analysis.png)
+
+### YARA Detection
+
+Same **Local Analysis** tab: switch to **YARA Detection** for the traffic rule engine — engine status, eight predefined rules (toggle, edit, delete), and **New Rule** for your own patterns. When the native `yara` module is not installed, scans still run using the built-in regex fallback (see [docs/local-analysis.md](docs/local-analysis.md)).
+
+![YARA Detection](docs/assets/yara-detection.png)
+
+**New Rule** opens the editor with a starter template (meta, `strings`, and `condition`). Edit the rule text, then **Save Rule** to add it as a custom pattern alongside the built-ins.
+
+![Adding a custom YARA rule](docs/assets/yara-new-rule.png)
+
+### Server setup
+
+Auto-detects Cursor / Codex / Windsurf configs, converts them to mcp-shark format, and patches the IDE to route through the proxy on start.
+
+![Server Setup](docs/assets/setup.png)
 
 ## Why mcp-shark?
 
@@ -45,7 +95,7 @@ Use mcp-shark findings as input to your own threat model, not as a complete audi
 
 | Feature | Description |
 |---------|-------------|
-| **35 security rules** | OWASP MCP Top 10 + Agentic Security Initiative + general checks |
+| **41 security rules** | OWASP MCP Top 10 + Agentic Security Initiative + AAuth visibility + general checks |
 | **Toxic flow analysis** | Cross-server attack path detection from tool capability heuristics |
 | **Attack walkthroughs** | Step-by-step exploit narratives from findings |
 | **Shark Score** | Transparent security posture score (0-100, A-F) |
@@ -61,8 +111,9 @@ Use mcp-shark findings as input to your own threat model, not as a complete audi
 | **YAML rules** | Per-project custom rules via `.mcp-shark/rules/` |
 | **GitHub Action** | CI/CD integration with SARIF upload |
 | **Interactive TUI** | lazygit-style terminal UI for scan, fix, and server browsing |
-| **Web UI** | Wireshark-like monitoring interface |
+| **Browser dashboard** | Live traffic, Local Analysis, YARA rules, AAuth Explorer, Playground, setup, and logs |
 | **Proxy toxic flows** | Local Analysis panel + `GET/POST /api/security/traffic-toxic-flows*` infer cross-server pairs from captured **tools/list** traffic (see [docs/local-analysis.md](docs/local-analysis.md)) |
+| **YARA-style traffic rules** | In **Local Analysis → YARA Detection**, enable or edit built-in pattern rules, add custom rules, and inspect engine status (native YARA when available, regex fallback otherwise) |
 | **Local static scans** | No hosted scan backend; `update-rules` is opt-in HTTPS to the registry |
 
 ## Quick Start
@@ -106,7 +157,7 @@ npx @mcp-shark/mcp-shark scan --ci --format sarif
 
 | Command | Description |
 |---------|-------------|
-| `scan` (default) | Run security scan with 35 rules |
+| `scan` (default) | Run security scan with 41 rules |
 | `lock` | Create `.mcp-shark.lock` file |
 | `lock --verify` | Verify current state matches lockfile |
 | `diff` | Show tool definition changes since last lock |
@@ -115,7 +166,7 @@ npx @mcp-shark/mcp-shark scan --ci --format sarif
 | `update-rules` | Download latest rule packs from remote registry |
 | `watch` | Watch config files and re-scan on changes |
 | `tui` | Interactive terminal UI (lazygit-style) |
-| `serve` | Start the web monitoring UI |
+| `serve` | Start the local proxy and monitoring dashboard |
 
 ## CLI flags
 
@@ -160,12 +211,12 @@ mcp-shark is aimed at **config and metadata you already have on disk** (plus opt
 | Area | Notes |
 |------|--------|
 | Install / run | Node.js 20+; `npx @mcp-shark/mcp-shark` |
-| Security rules | 35 checks — 24 declarative JSON packs, 11 JS where heuristics need code |
+| Security rules | 41 checks — 30 declarative JSON packs, 11 JS where heuristics need code |
 | Toxic flow analysis | Heuristic cross-server paths; quality depends on embedded `tools` / classifications |
 | Attack walkthroughs | Narratives derived from findings |
 | Auto-fix | Supported for a subset of issues; confirm changes in your repo |
 | Tool pinning | `.mcp-shark.lock` with SHA-256 hashes |
-| Live traffic | Web UI (`serve`) for monitoring; separate from static `scan` |
+| Live traffic | Dashboard (`serve`) for monitoring; separate from static `scan` |
 | Custom rules | YAML under `.mcp-shark/rules/` and JSON rule packs |
 | Findings & score | confirmed / advisory tiers plus Shark Score (0–100, A–F) |
 | IDE configs | 15 built-in paths + project-local `mcp.json` variants — see [Supported IDEs](#supported-ides) |
@@ -181,7 +232,7 @@ mcp-shark is aimed at **config and metadata you already have on disk** (plus opt
 
 The canonical **registry** (manifest, pack files, validation CI, and schema notes) lives in **[mcp-shark/rule-packs](https://github.com/mcp-shark/rule-packs)**. The npm package embeds copies; `update-rules` pulls the same artifacts into `.mcp-shark/rule-packs/`.
 
-mcp-shark ships with 24 declarative rules as JSON packs (OWASP MCP, Agentic Security Initiative, General Security), plus a **`toxic-flow-heuristics`** pack (`toxic_flow_rules` for cross-server composition). New vulnerability catalogs can be added as `.json` files — no JavaScript, no code changes.
+mcp-shark ships with 30 declarative rules as JSON packs (OWASP MCP, Agentic Security Initiative, General Security, AAuth Visibility), plus a **`toxic-flow-heuristics`** pack (`toxic_flow_rules` for cross-server composition). New vulnerability catalogs can be added as `.json` files — no JavaScript, no code changes.
 
 ```bash
 # Fetch latest rule packs from the registry
@@ -294,38 +345,48 @@ jobs:
 | Roo Code | `~/.roo-code/mcp.json` | ✅ |
 | Project (local) | `./mcp.json`, `./.mcp.json`, `./.mcp/config.json` | ✅ |
 
-## Security Rules (35)
+## Security Rules (41)
 
 <details>
 <summary>Full rule list</summary>
 
 ### OWASP MCP Top 10
-| ID | Rule | Severity |
-|----|------|----------|
-| MCP01 | Token Mismanagement | Critical |
-| MCP02 | Scope Creep | High |
-| MCP03 | Tool Poisoning | Critical |
-| MCP04 | Supply Chain | High |
-| MCP05 | Command Injection | Critical |
-| MCP06 | Prompt Injection | High |
-| MCP07 | Insufficient Auth | High |
-| MCP08 | Lack of Audit | Medium |
-| MCP09 | Shadow Servers | High |
-| MCP10 | Context Injection | High |
+| ID | Rule | Severity | Source |
+|----|------|----------|--------|
+| MCP01 | Token Mismanagement | Critical | declarative |
+| MCP02 | Scope Creep | High | declarative |
+| MCP03 | Tool Poisoning | Critical | declarative |
+| MCP04 | Supply Chain | High | declarative |
+| MCP05 | Command Injection | Critical | JS plugin |
+| MCP06 | Prompt Injection | High | declarative |
+| MCP07 | Insufficient Auth | High | declarative |
+| MCP08 | Lack of Audit | Medium | declarative |
+| MCP09 | Shadow Servers | High | declarative |
+| MCP10 | Context Injection | High | declarative |
 
 ### Agentic Security Initiative (ASI)
-| ID | Rule | Severity |
-|----|------|----------|
-| ASI01 | Goal Hijack | Critical |
-| ASI02 | Tool Misuse | High |
-| ASI03 | Identity Abuse | High |
-| ASI04 | Supply Chain | High |
-| ASI05 | Remote Code Execution | Critical |
-| ASI06 | Memory Poisoning | High |
-| ASI07 | Insecure Communication | Medium |
-| ASI08 | Cascading Failures | Medium |
-| ASI09 | Trust Exploitation | High |
-| ASI10 | Rogue Agent | Critical |
+| ID | Rule | Severity | Source |
+|----|------|----------|--------|
+| ASI01 | Goal Hijack | Critical | declarative |
+| ASI02 | Tool Misuse | High | declarative |
+| ASI03 | Identity Abuse | High | declarative |
+| ASI04 | Supply Chain | High | declarative |
+| ASI05 | Remote Code Execution | Critical | JS plugin |
+| ASI06 | Memory Poisoning | High | declarative |
+| ASI07 | Insecure Communication | Medium | declarative |
+| ASI08 | Cascading Failures | Medium | declarative |
+| ASI09 | Trust Exploitation | High | declarative |
+| ASI10 | Rogue Agent | Critical | declarative |
+
+### AAuth Visibility (informational)
+| ID | Description | Severity |
+|----|-------------|----------|
+| `aauth-agent-identity-observed` | `aauth:<local>@<domain>` agent identity in tool/prompt/resource/packet | Low |
+| `aauth-jwks-discovery-url` | URLs containing `/.well-known/aauth` or `/jwks` | Low |
+| `aauth-http-message-signature-observed` | RFC 9421 `Signature-Input` / `Signature` headers in captured traffic | Low |
+| `aauth-mission-context-observed` | `AAuth-Mission` headers in captured traffic | Low |
+| `aauth-requirement-challenge-observed` | `AAuth-Requirement` response headers (resource asking for AAuth) | Low |
+| `aauth-bearer-token-coexists-with-aauth` | Same packet has both Bearer token and AAuth signature | Medium |
 
 ### General Security
 | Rule | Severity |
@@ -348,9 +409,9 @@ jobs:
 
 </details>
 
-## Web UI
+## Browser dashboard
 
-MCP Shark also includes a Wireshark-like web interface for real-time MCP traffic monitoring:
+MCP Shark ships an **in-browser dashboard** on the local proxy for real-time MCP traffic, analysis, and exploration:
 
 ```bash
 npx @mcp-shark/mcp-shark serve --open
@@ -362,11 +423,23 @@ Same as the older shortcut (no `serve` subcommand):
 npx @mcp-shark/mcp-shark --open
 ```
 
-The web UI provides:
-- Multi-server aggregation and real-time monitoring
-- Interactive playground for testing tools, prompts, and resources
-- Local security analysis with pattern-based detection
-- API documentation with interactive testing
+The dashboard provides:
+- Multi-server aggregation and real-time traffic capture (filters, export, AAuth posture chips)
+- **MCP Playground** — call tools, prompts, and resources through the proxy against a selected upstream
+- **Local Analysis** — OWASP-style static scan over captured traffic; **YARA Detection** for traffic pattern rules (native engine when installed, regex fallback otherwise)
+- **AAuth Explorer** — graph of Agent / Mission / Resource / signing / access signals observed in traffic
+- **Smart Scan** — optional AI-backed scan (requires a configured API token)
+- In-app API docs, server setup, logs, and graceful shutdown
+
+### Zero-touch first boot
+
+The dashboard bootstraps itself the first time you launch it on a new machine — no Setup wizard click required:
+
+1. If `~/.mcp-shark/mcps.json` already declares upstreams (e.g. from a previous run, hand-edit, or `testbed:up`), the proxy starts directly with that config.
+2. Otherwise, on a brand-new install (no `~/.mcp-shark` at all), MCP Shark scans for a real editor MCP config (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, `~/.codex/config.toml`). If one is found with actual upstreams, it auto-imports them, writes `~/.mcp-shark/mcps.json`, starts the proxy, and patches the editor config so the editor routes through the proxy.
+3. If neither path applies, the UI starts in monitoring-only mode and the Setup panel is still available for manual configuration.
+
+To re-trigger first-boot behavior on a machine, remove `~/.mcp-shark/` and restart the UI.
 
 ## Architecture
 
@@ -377,24 +450,24 @@ The web UI provides:
 │  update-rules · serve                              │
 ├──────────────┬──────────────┬──────────────────────┤
 │  ConfigScanner│  ScanService  │  StaticRulesService  │
-│  15 IDEs      │  orchestrator │  35 rules            │
+│  15 IDEs      │  orchestrator │  41 rules            │
 ├──────────────┴──────────────┴──────────────────────┤
 │  Data layer (JSON + user YAML/JSON overrides)      │
 │  ┌────────────┬──────────────┬───────────────────┐ │
 │  │ rule-packs │ secret-      │ tool-             │ │
-│  │ (24 rules) │ patterns.json│ classifications   │ │
+│  │ (30 rules) │ patterns.json│ classifications   │ │
 │  ├────────────┼──────────────┼───────────────────┤ │
 │  │ toxic-flow │ rule-        │ .mcp-shark/*.yaml │ │
 │  │ rules.json │ sources.json │ (user overrides)  │ │
 │  └────────────┴──────────────┴───────────────────┘ │
 ├────────────────────────────────────────────────────┤
 │  JS plugins (11 rules needing algorithmic logic)   │
-│  + DeclarativeRuleEngine (24 pattern-based rules)  │
+│  + DeclarativeRuleEngine (30 pattern-based rules)  │
 └────────────────────────────────────────────────────┘
 ```
 
 **Design principles:**
-- **Data-first** — Declarative rules, secret patterns, tool classifications, and toxic-flow defaults ship as JSON; **24** of **35** rules are pattern packs you can extend or override without forking those definitions.
+- **Data-first** — Declarative rules, secret patterns, tool classifications, and toxic-flow defaults ship as JSON; **30** of **41** rules are pattern packs you can extend or override without forking those definitions.
 - **User-overridable** — Built-in data can be extended via `.mcp-shark/*.yaml` (and JSON pack drops) as documented above.
 - **Hybrid rule engine** — The other **11** rules are JS plugins where heuristics need code. Both sources are merged at scan time.
 - **Zero-config scanning** — `npx` and go. Auto-detects the IDE paths below plus project-local `mcp.json` variants.
@@ -405,9 +478,15 @@ The web UI provides:
 - **[Getting Started](docs/getting-started.md)** — Installation & setup
 - **[Features](docs/features.md)** — Detailed feature documentation
 - **[User Guide](docs/user-guide.md)** — Complete usage guide
-- **[Local Analysis](docs/local-analysis.md)** — Static security analysis
+- **[Configuration](docs/configuration.md)** — Configuration files & environment variables
+- **[Local Analysis](docs/local-analysis.md)** — Static security analysis & YARA traffic rules
+- **[AAuth Visibility](docs/aauth-visibility.md)** — RFC 9421 / AAuth observability
 - **[Architecture](docs/architecture.md)** — System design
+- **[Database Architecture](docs/database-architecture.md)** — SQLite schema reference
 - **[API Reference](docs/api-reference.md)** — API endpoints
+- **[Troubleshooting](docs/troubleshooting.md)** — Common issues & fixes
+- **[Development](docs/development.md)** — Contributing & project conventions
+- **[Package inspection](docs/package-inspection.md)** — npm package layout
 
 ## Requirements
 
@@ -423,6 +502,16 @@ Source-Available Non-Commercial License
 
 See [LICENSE](LICENSE) for full terms.
 
+## CLI demo
+
+Same one-liner as **[Quick Start](#quick-start)** (default `scan`). Terminal output depends on your config:
+
+```bash
+npx @mcp-shark/mcp-shark
+```
+
+![mcp-shark demo](docs/assets/demo.gif)
+
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/mcp-shark/mcp-shark/issues)

package/core/cli/ListCommand.js

@@ -5,6 +5,7 @@
  */
 import Table from 'cli-table3';
 import kleur from 'kleur';
+import { inspectServerConfigForAauth } from '#core/services/security/aauthParser.js';
 import { getAllServers, scanIdeConfigs } from './ConfigScanner.js';
 import { TOOL_CLASSIFICATIONS } from './ToolClassifications.js';
 import { S } from './symbols.js';
@@ -91,11 +92,40 @@ function renderTerminalInventory(servers, ideResults) {
   console.log(table.toString());
   console.log('');
 
+  renderAauthSummary(servers);
   renderIdeSummary(ideResults);
 
   return 0;
 }
 
+/**
+ * Print a single-line AAuth advertisement summary across all detected servers.
+ * Visibility-only: this only checks for AAuth-shaped fields in the static config
+ * (agent IDs, JWKS URLs, .well-known/aauth references). It does not connect.
+ */
+function renderAauthSummary(servers) {
+  let advertised = 0;
+  for (const server of servers) {
+    if (inspectServerConfigForAauth(server.config)) {
+      advertised += 1;
+    }
+  }
+  const remaining = servers.length - advertised;
+  if (servers.length === 0) {
+    return;
+  }
+  console.log(kleur.bold('  AAuth Visibility'));
+  console.log(
+    `  ${kleur.green(S.pass)} ${advertised} server${advertised === 1 ? '' : 's'} advertise AAuth · ${kleur.dim(`${remaining} do not`)}`
+  );
+  console.log(
+    kleur.dim(
+      '  Observed only — mcp-shark does not verify AAuth identity. See https://www.aauth.dev'
+    )
+  );
+  console.log('');
+}
+
 /**
  * Render a summary of which IDEs were detected
  */
@@ -128,6 +158,7 @@ function renderJsonInventory(servers, ideResults) {
       tool_count: getToolCount(s),
       command: s.config?.command || null,
       args_present: hasArgsPresent(s.config),
+      aauth: inspectServerConfigForAauth(s.config),
     })),
   };
   console.log(JSON.stringify(output, null, 2));

package/core/cli/data/rule-packs/aauth-visibility.json

@@ -0,0 +1,117 @@
+{
+  "schema_version": "1.0",
+  "pack_id": "aauth-visibility",
+  "pack_name": "AAuth Visibility",
+  "version": "1.0.0",
+  "updated": "2026-04-26",
+  "source_url": "https://github.com/dickhardt/AAuth",
+  "rules": [
+    {
+      "id": "aauth-agent-identity-observed",
+      "name": "AAuth Agent Identity Observed",
+      "owasp_id": "INFO",
+      "severity": "low",
+      "type": "aauth-visibility",
+      "description": "An AAuth agent identifier (aauth:local@domain) was observed in metadata. This is informational only — mcp-shark does not verify cryptographic identity.",
+      "recommendation": "Confirm the agent identifier is expected for this server. See https://www.aauth.dev for background on AAuth agent identities.",
+      "scope": ["tool", "prompt", "resource", "packet"],
+      "match_mode": "first",
+      "patterns": [
+        {
+          "regex": "aauth:[A-Za-z0-9._-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}",
+          "label": "AAuth agent ID",
+          "flags": ""
+        }
+      ]
+    },
+    {
+      "id": "aauth-jwks-discovery-url",
+      "name": "AAuth JWKS or Well-Known URL Observed",
+      "owasp_id": "INFO",
+      "severity": "low",
+      "type": "aauth-visibility",
+      "description": "A JWKS or .well-known/aauth URL was observed. This typically indicates the resource is AAuth-aware.",
+      "recommendation": "If this URL is unexpected, investigate which agent or resource is publishing it.",
+      "scope": ["tool", "prompt", "resource", "packet"],
+      "match_mode": "first",
+      "patterns": [
+        { "regex": "/\\.well-known/aauth", "label": ".well-known/aauth path", "flags": "i" },
+        { "regex": "https?://[^\\s\"']+/jwks(?:\\.json)?", "label": "JWKS URL", "flags": "i" }
+      ]
+    },
+    {
+      "id": "aauth-http-message-signature-observed",
+      "name": "HTTP Message Signature Observed",
+      "owasp_id": "INFO",
+      "severity": "low",
+      "type": "aauth-visibility",
+      "description": "An RFC 9421 HTTP Message Signature appears in captured traffic. mcp-shark records this as observed only — it does not verify the signature.",
+      "recommendation": "Use an AAuth-capable verifier to confirm signature validity. mcp-shark's role here is observability.",
+      "scope": ["packet"],
+      "match_mode": "first",
+      "patterns": [
+        {
+          "regex": "\"signature-input\"\\s*:\\s*\"[^\"]+\"",
+          "label": "Signature-Input header",
+          "flags": "i"
+        },
+        {
+          "regex": "\"signature\"\\s*:\\s*\"[^\"]*=:[A-Za-z0-9+/=]+:\"",
+          "label": "Signature header (sf-binary)",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "aauth-mission-context-observed",
+      "name": "AAuth Mission Context Observed",
+      "owasp_id": "INFO",
+      "severity": "low",
+      "type": "aauth-visibility",
+      "description": "An AAuth-Mission header was observed in captured traffic. Missions group calls under a single user-consented scope.",
+      "recommendation": "Use the mission timeline view in the UI to inspect related calls under the same mission.",
+      "scope": ["packet"],
+      "match_mode": "first",
+      "patterns": [
+        { "regex": "\"aauth-mission\"\\s*:", "label": "AAuth-Mission header", "flags": "i" }
+      ]
+    },
+    {
+      "id": "aauth-requirement-challenge-observed",
+      "name": "AAuth Requirement Challenge Observed",
+      "owasp_id": "INFO",
+      "severity": "low",
+      "type": "aauth-visibility",
+      "description": "An AAuth-Requirement response header was observed. The resource is asking the client to upgrade to AAuth.",
+      "recommendation": "If you control the calling agent, consider upgrading to AAuth — see https://www.aauth.dev.",
+      "scope": ["packet"],
+      "match_mode": "first",
+      "patterns": [
+        { "regex": "\"aauth-requirement\"\\s*:", "label": "AAuth-Requirement header", "flags": "i" }
+      ]
+    },
+    {
+      "id": "aauth-bearer-token-coexists-with-aauth",
+      "name": "Bearer Token Coexists With AAuth Headers",
+      "owasp_id": "MCP01",
+      "severity": "medium",
+      "type": "aauth-visibility",
+      "description": "A request carries both a Bearer token and AAuth identity headers. AAuth replaces bearer credentials — coexisting both is the worst-of-both-worlds pattern called out by the AAuth project.",
+      "recommendation": "Migrate the calling agent fully to AAuth; remove the long-lived bearer token once signed identity is in place.",
+      "scope": ["packet"],
+      "match_mode": "all_matches",
+      "patterns": [
+        {
+          "regex": "\"authorization\"\\s*:\\s*\"Bearer\\s+[^\"]+\"[\\s\\S]*\"signature-input\"",
+          "label": "Bearer + Signature-Input",
+          "flags": "i"
+        },
+        {
+          "regex": "\"signature-input\"[\\s\\S]*\"authorization\"\\s*:\\s*\"Bearer",
+          "label": "Signature-Input + Bearer",
+          "flags": "i"
+        }
+      ]
+    }
+  ]
+}

package/core/configs/environment.js

@@ -12,10 +12,12 @@ export const Environment = {
   },
   /**
    * Get UI server port
+   * Honours UI_PORT first, then the documented MCP_SHARK_PORT alias.
    * @returns {number} UI server port (default: 9853)
    */
   getUiPort() {
-    const port = Number.parseInt(process.env.UI_PORT, 10);
+    const raw = process.env.UI_PORT ?? process.env.MCP_SHARK_PORT;
+    const port = Number.parseInt(raw, 10);
     return Number.isNaN(port) ? Server.DEFAULT_UI_PORT : port;
   },
 

package/core/configs/index.js

@@ -1,17 +1,15 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { Environment } from './environment.js';
 
 export { Environment } from './environment.js';
 
-const WORKING_DIRECTORY_NAME = '.mcp-shark';
 const MCP_CONFIG_NAME = 'mcps.json';
 const APP_DB_DIR_NAME = 'db';
 const APP_DB_FILE_NAME = 'mcp-shark.sqlite';
-const HELP_STATE_NAME = 'help-state.json';
 
 export function getWorkingDirectory() {
-  return join(homedir(), WORKING_DIRECTORY_NAME);
+  return Environment.getMcpSharkHome();
 }
 
 export function getDatabasePath() {
@@ -61,62 +59,3 @@ export function ensureDirectoryExists(filePath) {
     mkdirSync(dir, { recursive: true });
   }
 }
-
-export function getHelpStatePath() {
-  return join(getWorkingDirectory(), HELP_STATE_NAME);
-}
-
-export function readHelpState() {
-  try {
-    const helpStatePath = getHelpStatePath();
-    if (existsSync(helpStatePath)) {
-      const content = readFileSync(helpStatePath, 'utf8');
-      const state = JSON.parse(content);
-      // Ensure we have the expected structure
-      return {
-        dismissed: state.dismissed || false,
-        tourCompleted: state.tourCompleted || false,
-        dismissedAt: state.dismissedAt || null,
-        version: state.version || '1.0.0',
-      };
-    }
-    return {
-      dismissed: false,
-      tourCompleted: false,
-      dismissedAt: null,
-      version: '1.0.0',
-    };
-  } catch (_error) {
-    // Error reading help state - return defaults
-    return {
-      dismissed: false,
-      tourCompleted: false,
-      dismissedAt: null,
-      version: '1.0.0',
-    };
-  }
-}
-
-export function writeHelpState(state) {
-  try {
-    const helpStatePath = getHelpStatePath();
-    prepareAppDataSpaces(); // Ensure directory exists
-
-    // Merge with existing state to preserve other fields
-    const existingState = readHelpState();
-    const newState = {
-      ...existingState,
-      ...state,
-      dismissedAt:
-        state.dismissed || state.tourCompleted
-          ? new Date().toISOString()
-          : existingState.dismissedAt,
-      version: '1.0.0',
-    };
-
-    writeFileSync(helpStatePath, JSON.stringify(newState, null, 2));
-    return true;
-  } catch (_error) {
-    return false;
-  }
-}

package/core/mcp-server/index.js

@@ -142,7 +142,10 @@ export async function startMcpSharkServer(options = {}) {
       throw new Error('auditLogger is required. Call initAuditLogger() and pass it in options.');
     }
     const auditLogger = providedAuditLogger;
-    const externalServersResult = await runAllExternalServers(serverLogger, configPath);
+    const externalServersResult = await runAllExternalServers(serverLogger, configPath, {
+      selfPort: port,
+      allowEmpty: true,
+    });
 
     if (isError(externalServersResult)) {
       serverLogger.error(

package/core/mcp-server/server/external/all.js

@@ -1,4 +1,4 @@
-import { CompositeError, getErrors } from '#core/libraries/ErrorLibrary.js';
+import { CompositeError, getErrors, isError } from '#core/libraries/ErrorLibrary.js';
 import { normalizeConfig } from './config.js';
 import { buildKv } from './kv.js';
 import { runExternalServer } from './single/run.js';
@@ -10,8 +10,15 @@ export class RunAllExternalServersError extends CompositeError {
   }
 }
 
-export async function runAllExternalServers(logger, parsedConfig) {
-  const configs = normalizeConfig(parsedConfig);
+export async function runAllExternalServers(logger, parsedConfig, options = {}) {
+  const configs = normalizeConfig(parsedConfig, { ...options, logger });
+  if (isError(configs)) {
+    return new RunAllExternalServersError(
+      `Failed to normalize upstream config: ${configs.message}`,
+      configs,
+      [configs]
+    );
+  }
   const results = await Promise.all(
     Object.entries(configs).map(([name, config]) => runExternalServer({ logger, name, config }))
   );