We release patches for security vulnerabilities for the following versions:

We take the security of Home Assistant MCP seriously. If you discover a security vulnerability, please follow these steps:

DO NOT open a public GitHub issue for security vulnerabilities.

Instead, please report security issues via:

1. GitHub Security Advisories (Preferred)

   • Navigate to the Security tab
   • Click "Report a vulnerability"
   • Fill in the details

2. Direct Contact

   • Contact the maintainers directly through GitHub
   • Include "SECURITY" in the subject line

Please provide:

• Description: Clear description of the vulnerability
• Impact: What could an attacker do?
• Reproduction Steps: How to reproduce the issue
• Environment: Versions, configurations, etc.
• Proof of Concept: Code or steps demonstrating the issue (if applicable)
• Suggested Fix: If you have ideas for a fix (optional)

• Acknowledgment: Within 48 hours
• Initial Assessment: Within 5 business days
• Status Updates: Every 7 days until resolved
• Fix Timeline: Depends on severity (see below)

• Never commit tokens to version control
• Use unique tokens for each deployment
• Rotate tokens regularly (quarterly recommended)
• Use descriptive names for tokens in Home Assistant
• Store tokens securely in environment variables or secret managers

• Use HTTPS for all Home Assistant connections
• Run behind a firewall when possible
• Use VPN for remote access
• Restrict network access to trusted sources
• Keep software updated (Bun, Node.js, dependencies)

Production checklist:

• Debug mode disabled (DEBUG=false)
• Rate limiting enabled and configured
• Strong authentication tokens in use
• HTTPS enabled for Home Assistant
• Security headers configured (in HTTP mode)
• Regular updates applied
• Audit logging enabled (if required)

• Input Validation: Sanitize all user inputs
• Output Encoding: Prevent XSS attacks
• Parameterized Queries: Prevent SQL injection
• Least Privilege: Run with minimal permissions
• Secure Dependencies: Keep dependencies updated
• Secret Management: Never hardcode secrets

• Run tests before committing: bun test
• Enable security scanning in CI/CD
• Review dependency vulnerabilities regularly
• Perform security audits for major releases
• Test authentication and authorization flows

• Token-based authentication via Home Assistant
• Token validation on every request
• Permission scoping from Home Assistant

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX=100        # Requests per window
RATE_LIMIT_WINDOW=60000   # Window in milliseconds

• XSS prevention on all inputs
• Command injection protection
• Path traversal protection
• SQL injection protection (where applicable)

• Content Security Policy (CSP)
• X-Frame-Options
• X-Content-Type-Options
• Strict-Transport-Security (HSTS)
• X-XSS-Protection

• We will respond promptly to security reports
• We will keep you informed of progress
• We will credit you in release notes (unless you prefer to remain anonymous)
• We will not take legal action against security researchers acting in good faith

We consider security research and vulnerability disclosure activities conducted in accordance with this policy to be:

• Authorized concerning any applicable anti-hacking laws
• Exempt from any restrictions in our Terms of Service
• Lawful and helpful to the overall security of the Internet

The following are not considered vulnerabilities:

• Denial of Service (DoS) attacks
• Social engineering attacks
• Physical attacks
• Issues requiring unlikely user interaction
• Issues in outdated/unsupported versions
• Issues with no security impact
• Rate limiting bypasses without security impact
• Missing security headers without demonstrated impact

• Watch this repository for security advisories
• Subscribe to GitHub Security Advisories
• Check CHANGELOG.md for security fixes
• Review Releases for security patches

1. Check Version: npm show @jango-blockchained/homeassistant-mcp version
2. Update Package: bun update @jango-blockchained/homeassistant-mcp
3. Test Changes: Verify functionality after updating
4. Monitor Logs: Check for any issues post-update

• Home Assistant Security
• OWASP Top 10
• Security Guide - Detailed security documentation
• Configuration Guide
• Troubleshooting

For general security questions (not vulnerabilities):

• Check the Security Guide
• Review the FAQ
• Ask in GitHub Discussions

For security vulnerabilities, always use private disclosure methods described above.

Thank you for helping keep Home Assistant MCP and our users safe! 🛡️