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.

Specky operates entirely locally. It makes zero outbound network requests. All data stays on the user's machine. The MCP server communicates only via stdio (JSON-RPC over stdin/stdout) or optional HTTP transport on localhost.

Specky has only 3 runtime dependencies:

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

# Check for known vulnerabilities
npm audit

# Check for outdated dependencies
npm outdated

We run npm audit in CI on every pull request. Any high or critical vulnerability blocks the merge.

When using HTTP transport mode (--http), bind to localhost only. Do not expose Specky to public networks without an authentication proxy.

• 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
• No shell command execution — branch names and PR payloads are data only, not executed

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.
• 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.4.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: