{"_id":"@blacksandscyber/mcp-server-shield","_rev":"2-2e5468886cf32cce08171cb5f3105dbf","name":"@blacksandscyber/mcp-server-shield","dist-tags":{"latest":"0.4.1"},"versions":{"0.3.0":{"name":"@blacksandscyber/mcp-server-shield","version":"0.3.0","keywords":["mcp","blacksands","shield","zero-trust","security","ai-agent","claude","broker","mtls"],"author":{"name":"Blacksands Cyber, Inc."},"license":"MIT","_id":"@blacksandscyber/mcp-server-shield@0.3.0","maintainers":[{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"}],"bin":{"shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp-http":"build/http-transport.js"},"dist":{"shasum":"18b45fef9a0230f6fb3843eb79a92f3ee640957a","tarball":"https://registry.npmjs.org/@blacksandscyber/mcp-server-shield/-/mcp-server-shield-0.3.0.tgz","fileCount":50,"integrity":"sha512-pd8eLfp5cHlRThbTrlPn3sl93Dkki2raB1SkLLmPamZHMZ6R6m0RY2FtWFkf4HqXdobtxQByaexxlE/0GUipMg==","signatures":[{"sig":"MEYCIQCIZM1SpE4cWk7MXu1p/szwIhyQUQMF3wvVx1tbA0QhUAIhAJaUz54N7b3ZEiTe/dE5mGVdxWap0QGbcO+UzkMAHYmx","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":320276},"main":"build/index.js","types":"./build/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"52fc2a2205295c6c0ea01f0ec670985424d787bb","scripts":{"dev":"tsc --watch","lint":"tsc --noEmit","test":"jest --forceExit --detectOpenHandles","build":"tsc","start":"node build/index.js","build:dxt":"bash scripts/build-dxt.sh","start:http":"node build/http-transport.js","prepublishOnly":"tsc"},"_npmUser":{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"},"_npmVersion":"10.8.2","description":"Blacksands Shield MCP Server — zero-trust security operations for AI agents. Installable in Claude Code (`claude mcp add shield -- shield-mcp`) and Claude Desktop (drag-and-drop .dxt).","directories":{},"_nodeVersion":"20.20.2","dependencies":{"glob":"^10.3.0","ssh2":"^1.17.0","axios":"^1.7.0","js-yaml":"^4.1.1","@aws-sdk/client-ssm":"^3.1032.0","@modelcontextprotocol/sdk":"^1.8.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ajv":"^8.20.0","jest":"^29.7.0","adm-zip":"^0.5.17","ts-jest":"^29.1.0","typescript":"^5.3.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","@types/ssh2":"^1.15.5","ajv-formats":"^3.0.1","@types/adm-zip":"^0.5.8","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-shield_0.3.0_1777158602723_0.24230287132457562","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@blacksandscyber/mcp-server-shield","version":"0.4.1","description":"Blacksands Shield MCP Server — zero-trust security operations for AI agents. Installable in Claude Code (`claude mcp add shield -- shield-mcp`) and Claude Desktop (drag-and-drop .dxt).","main":"build/index.js","bin":{"shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp":"dxt/scripts/setup.js","blacksands-shield-mcp-http":"build/http-transport.js"},"scripts":{"build":"tsc","build:dxt":"bash scripts/build-dxt.sh","start":"node build/index.js","start:http":"node build/http-transport.js","dev":"tsc --watch","test":"jest --forceExit --detectOpenHandles","lint":"tsc --noEmit","prepublishOnly":"tsc"},"keywords":["mcp","blacksands","shield","zero-trust","security","ai-agent","claude","broker","mtls"],"author":{"name":"Blacksands Cyber, Inc."},"license":"MIT","publishConfig":{"access":"public"},"dependencies":{"@aws-sdk/client-ssm":"^3.1032.0","@modelcontextprotocol/sdk":"^1.8.0","axios":"^1.7.0","glob":"^10.3.0","js-yaml":"^4.1.1","ssh2":"^1.17.0"},"devDependencies":{"@types/adm-zip":"^0.5.8","@types/jest":"^29.5.0","@types/js-yaml":"^4.0.9","@types/node":"^20.0.0","@types/ssh2":"^1.15.5","adm-zip":"^0.5.17","ajv":"^8.20.0","ajv-formats":"^3.0.1","jest":"^29.7.0","ts-jest":"^29.1.0","typescript":"^5.3.0"},"engines":{"node":">=18.0.0"},"_id":"@blacksandscyber/mcp-server-shield@0.4.1","gitHead":"891cb9592dcd81f7e3f19be2b0b1442e571d9d59","types":"./build/index.d.ts","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-CpTO3RLZvAeMT45sS/4rNd+lh1G6m9zjLGv/wAoFAB8/7mxblER1zgQhStUjnAefLSReaogRexXgLG7N5DUHDg==","shasum":"08f7b116e8944463931c30323bb874ffabf28669","tarball":"https://registry.npmjs.org/@blacksandscyber/mcp-server-shield/-/mcp-server-shield-0.4.1.tgz","fileCount":62,"unpackedSize":438626,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCf52PQOAoJFj8UJgti0fwc3vvbXgVsKZJE3ZkcQzKxBwIhAPNBRSJOycfS134cQYOnmYXZeko4WlCN+I2WOZsZiE0Q"}]},"_npmUser":{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"},"directories":{},"maintainers":[{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-shield_0.4.1_1782310190995_0.3133515394352928"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-25T23:10:02.623Z","modified":"2026-06-24T14:09:51.327Z","0.3.0":"2026-04-25T23:10:02.863Z","0.4.1":"2026-06-24T14:09:51.181Z"},"author":{"name":"Blacksands Cyber, Inc."},"license":"MIT","keywords":["mcp","blacksands","shield","zero-trust","security","ai-agent","claude","broker","mtls"],"description":"Blacksands Shield MCP Server — zero-trust security operations for AI agents. Installable in Claude Code (`claude mcp add shield -- shield-mcp`) and Claude Desktop (drag-and-drop .dxt).","maintainers":[{"name":"b0bmarl3y","email":"npawl@blacksandsinc.com"}],"readme":"# @blacksandscyber/mcp-server-shield\n\nZero-trust security operations for AI agents. **45 tools** for codebase analysis, application provisioning, mTLS certificate management, compliance reporting, and Receiver proxy lifecycle — exposed through the Model Context Protocol so Claude (or any MCP client) can drive Blacksands Shield directly.\n\nTwo install paths, depending on which Claude surface you use:\n\n| Surface | Install | Effort |\n|---|---|---|\n| **Claude Code** | `claude mcp add shield -- npx -y @blacksandscyber/mcp-server-shield` | One command |\n| **Claude Desktop** | Drag-and-drop the signed `.dxt` bundle | One drag |\n\n**Nine tools work without any Blacksands account.** Codebase scanning, framework detection, PII discovery, deployment guidance — installed and ready immediately. Sign up at [shield.blacksandscyber.online](https://shield.blacksandscyber.online) to unlock the remaining 36 tools (provisioning, compliance, Receiver management).\n\n---\n\n## Claude Code — one-line install\n\nThe fastest path. Works in any directory — Claude Code launches the MCP server when needed.\n\n```bash\n# Local-only mode — 9 [FREE] tools work immediately, no account needed\nclaude mcp add shield -- npx -y @blacksandscyber/mcp-server-shield\n\n# Verify\nclaude mcp list\n# shield: npx -y @blacksandscyber/mcp-server-shield - ✓ Connected\n```\n\nThen, in any Claude Code session:\n\n```\n> Scan my project at ~/some-app for security risks\n[Claude calls shield_scan_codebase, returns the security manifest]\n\n> What's the Blacksands deployment architecture?\n[Claude calls shield_guide_deployment, returns the authoritative overview]\n```\n\n### Bring your own credentials (full Shield API access)\n\nTo unlock all 45 tools, pass your existing cert bundle (issued through Overwatch / SysAdmin / a setup token):\n\n```bash\nclaude mcp add shield \\\n  --env SHIELD_AUTHORIZER_URL=https://mauth-beta.blacksandscyber.online \\\n  --env SHIELD_CLIENT_CERT=$HOME/.blacksands/mcp-certs/test-mcp9.crt \\\n  --env SHIELD_CLIENT_KEY=$HOME/.blacksands/mcp-certs/test-mcp9.key \\\n  --env SHIELD_AUTH_PASSWORD=$(cat $HOME/.blacksands/mcp-certs/.auth-password) \\\n  --env SHIELD_ORG_ID=blacksands \\\n  -- npx -y @blacksandscyber/mcp-server-shield\n```\n\nOr, for a one-time bootstrap with a setup token from your Blacksands admin:\n\n```bash\nclaude mcp add shield \\\n  --env SHIELD_SETUP_TOKEN=bss_xxxxxxxxxxxx \\\n  -- npx -y @blacksandscyber/mcp-server-shield\n```\n\nThe MCP server redeems the token on first launch, persists the cert bundle to `~/.blacksands/mcp-certs/`, and uses it for every subsequent run.\n\n---\n\n## Claude Desktop — drag-and-drop the .dxt\n\n1. Build (or download) `blacksands-shield-x.y.z.dxt`:\n   ```bash\n   cd mcp-server-blacksands-shield\n   MANIFEST=manifest-v2.json npm run build:dxt\n   # outputs build/blacksands-shield-x.y.z.dxt\n   ```\n2. Drag the `.dxt` onto the Claude Desktop app icon.\n3. Confirm install. Send a chat message — the MCP server starts on first tool call.\n\nFor the non-coder onboarding flow (admin issues a setup token, user clicks the install email), see [shield.blacksandscyber.online/docs/install](https://shield.blacksandscyber.online/docs/install).\n\n---\n\n## What you get\n\n### 9 [FREE] tools — no account needed\n\nRun on any local project. No network calls except for `shield_guide_deployment`'s overview text (which is bundled).\n\n| Tool | What it does |\n|---|---|\n| `shield_scan_codebase` | Composite scan — framework, endpoints, PII, services, datastores, manifest |\n| `shield_detect_framework` | Express, Flask, Rails, Next.js, Django, etc. |\n| `shield_scan_endpoints` | Extract HTTP/API routes with method + auth detection |\n| `shield_detect_pii` | SSN, credit card, health data, DOB; produces compliance hints |\n| `shield_detect_external_services` | Stripe, OpenAI, AWS, Firebase, Twilio, etc. |\n| `shield_detect_data_stores` | PostgreSQL, MongoDB, Redis, ORMs |\n| `shield_generate_manifest` | Assemble detection results into a Security Manifest JSON |\n| `shield_get_protection_requirements` | Plain-English checklist of what's needed to protect this app |\n| `shield_guide_deployment` | Authoritative deployment walkthrough — DigitalOcean Droplet, local-docker dev, etc. |\n\n### 36 tools requiring a Blacksands account\n\nProvisioning (`shield_create_org`, `shield_create_app`, `shield_provision_app`, `shield_install_agent_remotely`), compliance (`shield_compliance_report`, `shield_compliance_controls`), certs (`shield_list_certs`, `shield_revoke_cert`, `shield_rotate_cert`), Receiver lifecycle (`receiver_initialize`, `receiver_activate`, `receiver_onboard_service`, `receiver_health`), sessions (`shield_list_sessions`, `shield_revoke_session`), and emergency controls (`shield_emergency_lockdown`, `shield_lift_lockdown`).\n\nCalling any of these in local-only mode returns a friendly setup-token prompt instead of a stack trace.\n\n---\n\n## Configuration\n\nAll env vars are optional except where noted. Sensible defaults are baked in so the MCP server starts in local-only mode with zero configuration.\n\n| Var | Default | Required for | Description |\n|---|---|---|---|\n| `MCP_TRANSPORT` | `stdio` | — | Set to `local-only` to skip all auth and run only the 9 [FREE] tools |\n| `SHIELD_AUTHORIZER_URL` | `https://mauth-beta.blacksandscyber.online` | broker mode | Where the MCP client authenticates to Shield |\n| `SHIELD_SETUP_URL` | `https://onboard.beta.blacksandscyber.online` | token bootstrap | Where setup tokens are redeemed |\n| `SHIELD_SETUP_TOKEN` | (none) | first-time bootstrap | One-time `bss_…` token from a Blacksands admin |\n| `SHIELD_CLIENT_CERT` | (none) | broker mode | Path to mTLS client cert PEM file |\n| `SHIELD_CLIENT_KEY` | (none) | broker mode | Path to mTLS client key PEM file |\n| `SHIELD_AUTH_PASSWORD` | (none) | broker mode | Cert bundle's auth password |\n| `SHIELD_ORG_ID` | (none) | broker mode | Your organization id |\n| `SHIELD_CA_CERT` | bundled | optional | Path to Blacksands CA cert (override the bundled one) |\n| `LOG_LEVEL` | `info` | — | `debug`, `info`, `warn`, `error` |\n\nPersisted state lives in `~/.blacksands/mcp-certs/`:\n- `<client-name>.crt`, `<client-name>.key` — your mTLS bundle\n- `.auth-password`, `.client-name`, `.org-id`, `.last-token-prefix` — bookkeeping\n- `blacksands-ca.crt` — the Blacksands CA chain\n\nTo rotate credentials: `rm -rf ~/.blacksands/mcp-certs/`, then start the MCP server with a fresh `SHIELD_SETUP_TOKEN`.\n\n---\n\n## Accessing protected services\n\nOnce your agent has a valid mTLS cert (issued by Blacksands), reaching a protected service is **NOT** a single mTLS call. The auth chain is **bisected**: agent does mTLS to the **Authorizer** (which returns a list of services it's allowed to reach), then a SECOND independently-verified mTLS handshake to the **Receiver** (a public-IP edge proxy that forwards to the actual backend service).\n\n**For LLM-generated client code:** ask Claude to call **`broker_get_protocol_walkthrough`** before generating anything. That tool returns the authoritative protocol description plus copy-paste examples in Node.js, Python, and curl. Don't let Claude improvise the auth chain from training-data assumptions about mTLS — Blacksands is unusual: cert at TWO independent stages, backend service URL never reachable directly.\n\n```\n                  INTERNET\n                     │\n                     │  443 (mTLS, mandatory)\n                     ▼\n         ┌────────────────────┐\n         │     Authorizer     │  ← step 1: agent mTLS handshake\n         │  (mauth-…)         │  ← step 2: returns service-list with Receiver URLs\n         └────────────────────┘\n                     │\n                     │  agent picks service, builds URL with sessionToken\n                     ▼\n         ┌────────────────────┐\n         │     Receiver       │  ← step 4: SECOND mTLS handshake (same cert,\n         │  (public IP edge)  │            re-verified independently)\n         └─────────┬──────────┘\n                   │ private network\n                   ▼\n              backend service\n              (never reachable directly)\n```\n\nThe MCP server's `broker_get_protocol_walkthrough` tool is the canonical reference — fetched lazily when an LLM needs it. Same content is also surfaced as the `blacksands://broker-protocol` MCP resource for clients (like Claude Desktop) that prime context at session start.\n\nA minimal Node.js sketch:\n\n```js\nconst agent = new https.Agent({ cert, key, ca });\n\n// STEP 1+2: mTLS to Authorizer, get service URL + token\nconst auth = await axios.post(\n  'https://mauth-beta.blacksandscyber.online/api/agent/auth',\n  { password, serviceId: 'shield-api' },\n  { httpsAgent: agent }\n);\nconst receiverUrl = auth.data.service.serviceUrl;  // points at the Receiver, not the service\nconst [base, qs] = receiverUrl.split('?');\nconst token = new URLSearchParams(qs).get('token');\n\n// STEP 3+4+5+6: SAME agent reused for the second mTLS handshake\nconst api = axios.create({\n  baseURL: `${base}/v1`,\n  httpsAgent: agent,        // same cert presented again, Receiver re-verifies independently\n  params: { token },\n});\nconst orgs = await api.get('/orgs');\n```\n\nFull Node.js, Python, and curl examples — plus the anti-patterns to avoid — are in the tool's output.\n\n---\n\n## Verifying the install\n\n```bash\n# Should show \"shield: ... ✓ Connected\"\nclaude mcp list\n\n# Quickest check — call a [FREE] tool that doesn't need Shield API\nclaude --print \"What is the Blacksands deployment architecture? Use shield_guide_deployment.\"\n```\n\nThe MCP server logs to stderr (stdout is reserved for the MCP wire protocol). On macOS look in `~/Library/Logs/Claude/mcp-server-Shield.log` (Claude Desktop) or run with `claude --mcp-debug` (Claude Code).\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/b0bmarl3y/Blacksands_2_0.git\ncd Blacksands_2_0/mcp-server-blacksands-shield\nnpm install\nnpm run lint && npm test          # 137 tests, ~4s\nnpm run build                     # tsc → build/\nnode dxt/scripts/setup.js         # boot the server directly\n```\n\nTest harness layout:\n\n| Tier | Location | What it covers | Cadence |\n|---|---|---|---|\n| 1 | `tests/manifest.test.ts`, `tests/dxt-package.test.ts`, `tests/shield/deploy/*`, `tests/config.test.ts`, `tests/server-tags.test.ts` | DXT manifest spec, content invariants on tool output, mode dispatch, [FREE] tag discipline | Every commit |\n| 2 | `tests/harness/*` | MCP wire-protocol harness — spawns the compiled server and exercises tools/list + tools/call against a fixture project | Every PR |\n| 3 | `tests/integration/live-broker.test.ts` (gated) | Live broker chain canary against the real Shield API | Release / on-demand (`RUN_LIVE_INTEGRATION=1`) |\n| 4 | (manual checklist) | Drag-install validation + LLM behavior + destructive-tool exercise | Release prep |\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\nFor commercial support, custom integrations, or enterprise deployments (cryptographic remote attestation, HSM-backed cert storage, on-prem control plane), contact [support@blacksands.io](mailto:support@blacksands.io).\n","readmeFilename":"README.md"}