If you discover a security vulnerability in Specky, please report it responsibly:

1. Do NOT open a public issue.
2. Email paulasilvatech@github.com with:
   • Description of the vulnerability
   • Steps to reproduce
   • Impact assessment
   • Suggested fix (if any)
3. You will receive an acknowledgment within 48 hours.
4. A fix will be released within 7 days for critical issues.

All 58 MCP tool inputs are validated using Zod schemas with .strict() mode. No unknown fields are accepted. This prevents injection of unexpected parameters through the MCP JSON-RPC interface.

AI Client → JSON-RPC → Zod .strict() validation → Service layer

FileManager (the sole file I/O service) sanitizes all paths before any filesystem operation:

• Resolves paths relative to the workspace root
• Rejects paths containing .. sequences
• Blocks access outside the designated workspace directory
• All file operations are scoped to SDD_WORKSPACE or the current working directory

Specky does not use eval(), Function(), vm.runInNewContext(), or any dynamic code execution. Template rendering uses string replacement only — no template engines that execute code.

The Specky MCP server does not execute arbitrary shell commands or persist GitHub credentials. Generated agents may declare narrowly scoped Git, test, or release-gate capabilities, but the selected host runtime executes and approves those native tools. The optional GitHub MCP integration is registered only with specky install --integration=github; GitHub authentication and repository authorization remain with the signed-in host identity. See Target Capabilities.

The MCP server makes zero outbound network calls. All data stays on the user's machine. It communicates only via stdio (JSON-RPC over stdin/stdout) or optional HTTP transport on localhost, and this holds unconditionally — specky serve never performs the update check described below.

The CLI performs exactly one optional outbound call: a once-daily GET https://registry.npmjs.org/specky-sdd/latest to detect new releases, run after install/doctor/status/upgrade/--version and shown as an Update available: vX → vY banner. This is not telemetry — nothing is sent beyond the HTTP request itself: no identifiers, no usage data, no payload. The check fails silently when offline and is disabled automatically in CI (CI=true).

Opt out with either:

• SPECKY_NO_UPDATE_CHECK=1 in the environment, or
• update_check: false in .specky/config.yml

The local version-drift warning printed by specky doctor/specky status and at MCP server startup compares installed assets against the running version on disk — it involves no network at all.

Specky declares only 3 direct runtime dependencies. Their transitives are included in runtime audits and the published SBOM:

Runtime dependencies are kept intentionally small and are audited in CI.

• All log output goes to stderr — stdout is reserved for JSON-RPC protocol messages
• No sensitive data (credentials, tokens, file contents) is included in log messages
• Audit-relevant tool invocations are recorded only in the local .specs/ directory

# Block high/critical findings in the package shipped to users
npm run security:audit:runtime

# Report runtime and development findings; block critical findings
npm run security:audit:all

CI and publishing block high/critical findings in production dependencies and critical findings anywhere in the lockfile. The full audit still prints high findings from development tooling so they remain visible while an upstream-compatible fix is unavailable.

As of 2026-08-08, the direct MCP SDK range starts at ^1.30.0 and the lockfile resolves 1.30.0, avoiding the SDK data-isolation and ReDoS advisories affecting older releases. Its Hono dependency resolves to 4.12.33; npm advisories require 4.12.34, which is not yet available in the configured registry, leaving three moderate runtime findings. The development-only PostCSS path resolves NanoID 3.3.16; the zero-size generator advisory requires 3.3.17, also not yet available in that line. Do not use npm audit fix --force to cross declared major/version boundaries. These temporary residuals must be removed when compatible upstream releases become available.

Updating the npm package and upgrading a workspace are separate steps:

# Global installation
npm install -g specky-sdd@latest
cd your-project
specky upgrade
specky doctor

# Project-local installation
npm install --save-dev specky-sdd@latest
npx specky upgrade
npx specky doctor

The npm command installs fixed Specky code and dependencies. specky upgrade does not modify npm packages; it migrates supported workspace config, refreshes generated assets, and re-pins MCP registration to the package version already installed. specky doctor then verifies installed asset hashes.

HTTP transport (--http) binds to 127.0.0.1 by default. Binding to a non-loopback address requires an explicit --host and prints a warning. Set SDD_HTTP_TOKEN (shared token) or SDD_HTTP_TOKENS_FILE (named tokens mapping to principal + role) to require an Authorization: Bearer <token> header on every /mcp request (the /health probe stays open). Even so, do not expose Specky to public networks without a TLS-terminating reverse proxy. Hosted, air-gapped, and container deployment patterns: docs/ENTERPRISE-DEPLOYMENT.md.

The audit trail's plain hash chain detects corruption but not deliberate rewriting by a workspace writer; configure an HMAC key (held outside the workspace) to make entries tamper-evident, and anchor the current_hash from sdd_verify_audit externally to detect tail truncation.

• TypeScript strict mode enabled — no implicit any, no unchecked index access
• Zero any types in source code — enforced by CI
• All schemas use .strict() — rejects unknown fields
• FileManager is the sole I/O boundary — no direct fs calls in tools or other services
• The Specky MCP server does not execute shell commands; target runtimes may execute only the explicitly declared, host-approved agent capabilities

If you must use HTTP mode (--http):

1. [ ] Bind to localhost only (default behavior)
2. [ ] Place behind reverse proxy with TLS (HTTPS)
3. [ ] Add authentication to the reverse proxy
4. [ ] Set firewall rules to restrict access
5. [ ] Use a unique PORT via environment variable
6. [ ] Monitor access logs on the reverse proxy

Example secure deployment with nginx:

server {
    listen 443 ssl;
    server_name specky.internal.company.com;

    ssl_certificate     /etc/ssl/certs/specky.crt;
    ssl_certificate_key /etc/ssl/private/specky.key;

    # Require authentication
    auth_basic "Specky MCP Server";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:3200;
        proxy_set_header Host $host;
    }
}

These guarantees describe the intended product boundary. Known implementation gaps are tracked in docs/DETERMINISM.md and docs/ENTERPRISE-CONTROLS.md.

• No outbound network calls from core MCP tools — optional external MCP integrations are returned as routing payloads for the AI client to execute. The CLI's once-daily update check (see Network Calls) is the package's only outbound call; it is opt-out and never runs in specky serve.
• No dynamic code execution — no eval(), Function(), or vm.runInNewContext() in the Specky core.
• No credential storage by design — no API keys, tokens, or passwords are intentionally stored by Specky.
• Workspace-scoped I/O is the target boundary — FileManager.sanitizePath() enforces this for core file operations; document import hardening is tracked as an enterprise remediation item.
• No sensitive operational logging by design — logs go to stderr and should contain only operational messages.
• Explicit hook execution is administrative — specky hooks intentionally runs installed hook scripts for diagnostics and compatibility testing.

See docs/SYSTEM-DESIGN.md for the complete security architecture with threat model.

Running npx -y specky-sdd@latest without a pinned version downloads the latest package from npm on every invocation. This creates a supply-chain exposure: a compromised npm registry entry or a typosquat could execute malicious code in your environment before Specky even starts.

Recommended mitigations (ordered by risk reduction):

Workspace isolation pattern (CI/CD):

# Install into a local vendor directory — no global write permissions needed
npm install specky-sdd@3.6.0 --prefix ./vendor --ignore-scripts
./vendor/node_modules/.bin/specky install
./vendor/node_modules/.bin/specky doctor     # integrity check

CLI binary entry points (both ship in the same package):

• specky — unified CLI (install, doctor, status, upgrade, hooks, serve)
• specky-sdd — legacy alias; with no subcommand it routes to specky serve (MCP stdio server), preserving any existing .mcp.json configs that reference specky-sdd directly

Install integrity check:

Every specky install produces .specky/install.lock with SHA256 of every deployed file. specky doctor validates these hashes — a tampered hook script or agent file is detected before any agent runs.

The --ignore-scripts flag prevents npm lifecycle scripts from running during install, which is a common supply-chain attack vector.

Specky addresses the 12 threat categories from the CoSAI MCP Security White Paper:

• npm audit command
• npm force configuration
• MCP SDK cross-client data isolation advisory
• MCP SDK ReDoS advisory
• Hono CORS ReDoS advisory
• NanoID zero-size generator advisory