PromptArchitect MCP

# npm Package Security Review Checklist > **Package:** `@promptarchitect/mcp-server` > **Version:** 0.1.6 > **Review Date:** _______________ > **Reviewer:** _______________ > **Status:** ⬜ Pending | ⬜ In Progress | ⬜ Approved | ⬜ Rejected This document provides a comprehensive security review process for the MCP npm package prior to publishing to the npm registry. It incorporates current best practices and addresses recent supply chain attack vectors reported in 2025. --- ## Pre-Review Setup Before starting the security review, ensure you have the following tools installed: ```bash # Required tools npm install -g npm-audit-resolver # For dependency auditing npm install -g snyk # For vulnerability scanning npm install -g secretlint # For secrets detection npm install -g license-checker # For license compliance # Verify installations npm audit --version snyk --version secretlint --version ``` --- ## 1. Code Review (Manual Code Inspection) ### 1.1 Source Code Integrity - [ ] **Verify all source files are committed** ```bash # Check for uncommitted changes git status git diff --stat ``` **Expected:** No uncommitted changes that could introduce unreviewed code. - [ ] **Review all TypeScript/JavaScript files for suspicious patterns** ```bash # Search for dangerous patterns grep -rn "eval\|Function\(" src/ grep -rn "child_process\|exec\|spawn" src/ grep -rn "require\s*\(" src/ # Dynamic requires in ESM grep -rn "process\.env" src/ grep -rn "fetch\|http\|https" src/ ``` **Expected:** Any matches should be justified and documented. - [ ] **Check for obfuscated or minified source code** ```bash # Ensure no minified code in src/ find src/ -name "*.js" -exec head -1 {} \; | grep -E "^.{500,}" ``` **Expected:** No minified files in source directory. ### 1.2 Entry Points Review - [ ] **Audit CLI entry point** ([src/cli.ts](src/cli.ts)) - Verify argument parsing is safe - Check for command injection vulnerabilities - Ensure no arbitrary code execution from user input - [ ] **Audit server entry point** ([src/server.ts](src/server.ts)) - Review MCP protocol handler implementation - Verify input validation on all tool calls - Check for prototype pollution vulnerabilities - [ ] **Review all tool implementations** ([src/tools/](src/tools/)) - Each tool must validate inputs using Zod schemas - No direct eval or dynamic code execution - External API calls must use validated URLs only ### 1.3 Input Validation - [ ] **Verify Zod schemas are comprehensive** ```bash # List all Zod schema definitions grep -rn "z\." src/ | head -50 ``` **Expected:** All user inputs have corresponding Zod validation. - [ ] **Test input validation with edge cases** - Empty strings - Very long strings (>100KB) - Unicode/special characters - Nested objects (prototype pollution test) ```typescript // Example prototype pollution test const malicious = JSON.parse('{"__proto__":{"admin":true}}'); ``` ### 1.4 Error Handling - [ ] **Ensure errors don't leak sensitive information** ```bash grep -rn "console\.\(log\|error\|warn\)" src/ grep -rn "stack\|trace" src/ ``` **Expected:** No stack traces or internal paths exposed to users. --- ## 2. Dependency Analysis (Scanning for Vulnerable Dependencies) ### 2.1 Audit Direct Dependencies - [ ] **Run npm audit** ```bash cd mcp-server npm audit npm audit --audit-level=moderate ``` **Expected:** No high or critical vulnerabilities. Document any moderate issues. - [ ] **Run Snyk security scan** ```bash snyk test snyk test --severity-threshold=medium ``` **Expected:** No high or critical vulnerabilities. - [ ] **Review each direct dependency** | Dependency | Version | Last Updated | Weekly Downloads | Justified? | |------------|---------|--------------|------------------|------------| | @google/generative-ai | ^0.21.0 | ___ | ___ | ⬜ | | @modelcontextprotocol/sdk | ^1.25.0 | ___ | ___ | ⬜ | | zod | ^3.25.0 | ___ | ___ | ⬜ | ```bash # Check package info npm info @google/generative-ai npm info @modelcontextprotocol/sdk npm info zod ``` ### 2.2 Audit Dev Dependencies - [ ] **Review dev dependencies for security** ```bash npm ls --dev --depth=0 ``` **Expected:** All dev dependencies are from trusted sources. - [ ] **Ensure dev dependencies don't leak to production** ```bash # Check files array in package.json cat package.json | grep -A 10 '"files"' ``` **Expected:** Only `dist`, `README.md`, `LICENSE` are published. ### 2.3 Transitive Dependency Analysis - [ ] **Generate full dependency tree** ```bash npm ls --all > dependency-tree.txt ``` - [ ] **Check for known vulnerable packages** ```bash # Check for recently compromised packages (2025 examples) npm ls | grep -iE "event-stream|flatmap-stream|ua-parser-js|coa|rc" ``` **Expected:** No matches with known compromised packages. - [ ] **Verify lockfile integrity** ```bash # Ensure package-lock.json is up to date npm ci # Check lockfile version grep '"lockfileVersion"' package-lock.json ``` **Expected:** lockfileVersion should be 3 (npm v7+). ### 2.4 License Compliance - [ ] **Check all dependency licenses** ```bash license-checker --summary license-checker --onlyAllow "MIT;Apache-2.0;ISC;BSD-2-Clause;BSD-3-Clause" ``` **Expected:** All licenses are permissive and compatible with MIT. --- ## 3. Supply Chain Security (Protecting Against Malicious Packages) ### 3.1 Package Identity Verification - [ ] **Verify npm organization ownership** ```bash npm org ls promptarchitect ``` **Expected:** Only authorized team members have publish access. - [ ] **Check package name for typosquatting risk** - Verify `@promptarchitect/mcp-server` doesn't conflict with existing packages - Check for similar package names that could confuse users ```bash npm search mcp-server npm search promptarchitect ``` ### 3.2 Build Pipeline Security - [ ] **Verify build output matches source** ```bash # Clean build npm run clean npm run build # Compare dist output ls -la dist/ ``` **Expected:** Only expected .js and .d.ts files in dist/. - [ ] **Check for build script tampering** ```bash cat package.json | grep -A 20 '"scripts"' ``` **Expected:** Scripts only run tsc, vitest, rimraf - no curl/wget/external downloads. - [ ] **Verify prepublishOnly script** ```bash # Should run: clean, build, test npm run prepublishOnly --dry-run ``` ### 3.3 Git History Integrity - [ ] **Check for unsigned commits in recent history** ```bash git log --show-signature -10 ``` **Recommended:** Enable commit signing for future releases. - [ ] **Verify no suspicious commits** ```bash # Check for large binary additions git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print $3, $4}' | sort -rn | head -20 ``` **Expected:** No unexpected large binary files. ### 3.4 Provenance & Attestation (npm 2025 Best Practice) - [ ] **Enable npm provenance** ```bash # In CI/CD pipeline, publish with provenance npm publish --provenance ``` **Expected:** Package will have cryptographic attestation of build origin. - [ ] **Add SLSA provenance metadata** Create `.github/workflows/publish.yml` with provenance: ```yaml - name: Publish with provenance run: npm publish --provenance --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} ``` --- ## 4. Secrets Management (Preventing Credential Exposure) ### 4.1 Scan for Hardcoded Secrets - [ ] **Run secretlint** ```bash npx secretlint "**/*" ``` **Expected:** No secrets detected. - [ ] **Run gitleaks (if available)** ```bash gitleaks detect --source . --verbose ``` - [ ] **Manual secret patterns check** ```bash # API keys grep -rn "AIza\|sk-\|pk_\|secret\|password\|token\|key" src/ # AWS credentials grep -rn "AKIA\|aws_access\|aws_secret" src/ # Private keys grep -rn "BEGIN.*PRIVATE KEY" src/ ``` **Expected:** No matches or only false positives (e.g., variable names). ### 4.2 Environment Variable Security - [ ] **Review environment variable usage** ```bash grep -rn "process\.env" src/ ``` | Variable | Purpose | Required? | Documented? | |----------|---------|-----------|-------------| | GEMINI_API_KEY | Gemini API access | Yes | ⬜ | | ___ | ___ | ___ | ⬜ | - [ ] **Ensure no default secrets in code** ```bash grep -rn "process\.env\.\w*\s*\|\|" src/ ``` **Expected:** No hardcoded fallback values for secrets. ### 4.3 .gitignore and .npmignore Audit - [ ] **Verify sensitive files are ignored** ```bash cat .gitignore cat .npmignore 2>/dev/null || echo "No .npmignore (using 'files' in package.json)" ``` **Expected:** `.env*`, `*.pem`, `*.key`, `secrets/` are ignored. - [ ] **Test what gets published** ```bash npm pack --dry-run ``` **Expected:** Only files listed in `package.json` `files` array. ### 4.4 Git History Secrets Check - [ ] **Scan git history for accidentally committed secrets** ```bash # Check if any .env files were ever committed git log --all --full-history -- "*.env" ".env*" # Comprehensive history scan git log -p --all -S "password" --source --all | head -100 ``` **Expected:** No secrets in git history. --- ## 5. Publishing Security (Securely Publishing to npm) ### 5.1 npm Account Security - [ ] **Enable 2FA on npm account** - Go to npmjs.com → Account → Security - Enable Two-Factor Authentication (required for publishing) - [ ] **Use granular access tokens** ```bash # Create automation token with limited scope npm token create --read-only=false --cidr=["192.168.1.0/24"] ``` **Expected:** Use scoped tokens, not legacy full-access tokens. - [ ] **Verify account has no active sessions from unknown locations** - Review npm account security settings - Check for suspicious access patterns ### 5.2 Pre-Publish Verification - [ ] **Verify package.json metadata** ```bash npm pkg get name version description license author repository ``` **Expected:** All fields are accurate and complete. - [ ] **Run prepublishOnly checks** ```bash npm run prepublishOnly ``` **Expected:** Clean build and all tests pass. - [ ] **Final package contents review** ```bash npm pack tar -tzf promptarchitect-mcp-server-*.tgz ``` **Expected:** Only expected files are included. ### 5.3 Publish Process - [ ] **Publish from clean environment** ```bash # Fresh clone git clone <repo> temp-publish cd temp-publish/mcp-server npm ci npm run prepublishOnly ``` - [ ] **Publish with provenance (CI/CD preferred)** ```bash # For manual publish (not recommended for production) npm publish --access public # For CI/CD with provenance (recommended) npm publish --provenance --access public ``` - [ ] **Verify published package** ```bash # Wait 1-2 minutes for registry propagation npm info @promptarchitect/mcp-server npm view @promptarchitect/mcp-server versions ``` ### 5.4 Post-Publish Verification - [ ] **Test installation from registry** ```bash mkdir test-install && cd test-install npm init -y npm install @promptarchitect/mcp-server npx promptarchitect-mcp --version ``` **Expected:** Package installs and runs correctly. - [ ] **Verify package integrity** ```bash npm view @promptarchitect/mcp-server dist.integrity ``` - [ ] **Set up package monitoring** - Subscribe to security advisories for your package - Enable Snyk or Socket.dev monitoring - Set up npm audit in CI for downstream users --- ## Security Review Summary ### Review Results | Category | Status | Issues Found | Remediation | |----------|--------|--------------|-------------| | Code Review | ⬜ Pass / ⬜ Fail | ___ | ___ | | Dependency Analysis | ⬜ Pass / ⬜ Fail | ___ | ___ | | Supply Chain Security | ⬜ Pass / ⬜ Fail | ___ | ___ | | Secrets Management | ⬜ Pass / ⬜ Fail | ___ | ___ | | Publishing Security | ⬜ Pass / ⬜ Fail | ___ | ___ | ### Final Approval - [ ] **All critical checks pass** - [ ] **All high-severity issues resolved** - [ ] **Medium-severity issues documented and accepted** - [ ] **Reviewer sign-off** **Approved by:** _______________ **Date:** _______________ **Version approved:** _______________ --- ## Appendix A: Quick Commands Reference ```bash # Full security scan (run from mcp-server directory) npm audit && \ snyk test && \ npx secretlint "**/*" && \ license-checker --summary && \ npm pack --dry-run # Pre-publish checklist npm run clean npm ci npm run prepublishOnly npm pack tar -tzf *.tgz # Publish (CI/CD) npm publish --provenance --access public ``` ## Appendix B: 2025 Supply Chain Attack Reference Recent npm supply chain attacks to be aware of: | Attack | Date | Vector | Mitigation | |--------|------|--------|------------| | Typosquatting campaigns | 2025 | Similar package names | Verify exact package names | | Maintainer account compromise | 2025 | Stolen credentials | 2FA, access tokens | | Dependency confusion | 2024-2025 | Private/public namespace collision | Use scoped packages | | Build script injection | 2025 | Malicious postinstall scripts | Audit install scripts | | Provenance spoofing | 2025 | Fake build attestations | Verify SLSA provenance | ## Appendix C: Recommended CI/CD Security Pipeline ```yaml # .github/workflows/security.yml name: Security Checks on: push: branches: [main] pull_request: branches: [main] jobs: security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '22' - name: Install dependencies run: npm ci working-directory: ./mcp-server - name: Run npm audit run: npm audit --audit-level=high working-directory: ./mcp-server - name: Run Snyk uses: snyk/actions/node@master env: SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }} with: args: --severity-threshold=high - name: Check for secrets run: npx secretlint "**/*" working-directory: ./mcp-server - name: License check run: npx license-checker --onlyAllow "MIT;Apache-2.0;ISC;BSD-2-Clause;BSD-3-Clause" working-directory: ./mcp-server ``` --- *Last updated: December 2025* *Review this checklist before each npm publish*