hassio-addons/.claude/SECURITY_REVIEW_CHECKLIST.md

Security Review Checklist for Home Assistant Add-ons

🛡️ Pre-Submission Security Review

Use this checklist before submitting any new add-on or major changes to existing add-ons.

✅ Critical Security Requirements

File Permissions

• No chmod 777 used anywhere in the add-on
• Scripts use chmod 755 or chmod +x for executables
• Configuration files use chmod 644 or more restrictive
• Sensitive files (keys, certs) use chmod 600 or more restrictive

Container Privileges

• Add-on requests minimal required privileges only
• privileged array contains only necessary capabilities
• No blanket SYS_ADMIN unless absolutely required with justification
• Device access limited to specific devices needed
• Network access restricted to required ports/protocols

Script Security

• All scripts use set -e for error handling
• All scripts use set -u for undefined variable checking
• All scripts use set -o pipefail for pipeline error propagation
• Remote downloads include integrity verification (checksums)
• No remote script execution without verification

Input Validation

• All user inputs validated for format and safety
• Path inputs sanitized to prevent directory traversal
• Network inputs validated (URLs, IPs, ports)
• Configuration values have appropriate bounds checking

🔧 Dockerfile Security

Base Images

• Uses official Home Assistant base images
• Base image version is pinned (not latest)
• Base image is regularly updated

Build Process

• No secrets in build arguments or environment variables
• Build dependencies are pinned to specific versions
• Multi-stage builds used where appropriate to reduce attack surface
• Unnecessary packages removed after build

Runtime Security

• Non-root user used where possible
• Health checks implemented
• Proper signal handling for graceful shutdown
• Resource limits defined

🚪 Network Security

Port Configuration

• Only required ports exposed
• Internal services not exposed unnecessarily
• Ingress configuration reviewed for security
• SSL/TLS used for external communications

Service Discovery

• Service discovery limited to required services
• Authentication required for service access
• Service communication encrypted where sensitive

📁 Data Security

File System Access

• Read-only file system where possible
• Temporary files in appropriate directories
• Sensitive data not logged
• File permissions set appropriately on mounted volumes

Configuration Management

• Sensitive configuration values use Home Assistant secrets
• Default configurations are secure
• Configuration validation prevents dangerous settings
• Configuration files not world-readable

🔍 Code Quality

Error Handling

• Graceful error handling implemented
• Error messages don't leak sensitive information
• Appropriate logging levels used
• Failed operations don't leave system in unsafe state

Dependencies

• All dependencies are from trusted sources
• Dependencies are pinned to specific versions
• Vulnerability scanning performed on dependencies
• Unused dependencies removed

📋 AppArmor Profile

Profile Completeness

• AppArmor profile exists and is tested
• Profile follows principle of least privilege
• No blanket capability grants without justification
• File access restrictions appropriate
• Network access restrictions defined

Profile Testing

• Profile tested with add-on functionality
• Profile doesn't break legitimate operations
• Profile logs violations for monitoring
• Profile updated when add-on functionality changes

📚 Documentation

Security Documentation

• Security considerations documented in README
• Required privileges explained and justified
• Known security limitations documented
• Upgrade/migration security notes provided

Configuration Documentation

• Security-relevant configuration options explained
• Default security settings documented
• Best practices for secure configuration provided
• Examples show secure configurations

🧪 Testing

Security Testing

• Add-on tested with minimal privileges
• Input validation tested with malicious inputs
• Error conditions tested for security implications
• Integration testing performed with Home Assistant security features

Automated Testing

• Security linting passes (shellcheck, hadolint, etc.)
• Dependency vulnerability scanning passes
• Container image scanning passes
• Configuration validation testing passes

🚨 Red Flags - Automatic Review Required

The following items require mandatory security team review:

• chmod 777 anywhere in the code
• SYS_ADMIN or DAC_OVERRIDE capabilities
• Network host mode requested
• Privileged container mode requested
• Direct hardware device access
• Custom AppArmor profile bypass
• Remote code execution capabilities
• Cryptographic key generation or storage
• User authentication mechanisms
• File system modifications outside add-on directories

📝 Review Sign-off

Reviewer Information

• Reviewer Name: ________________
• Review Date: ________________
• Add-on Name: ________________
• Add-on Version: ________________

Security Assessment

• Risk Level: [ ] Low [ ] Medium [ ] High [ ] Critical
• Approval Status: [ ] Approved [ ] Conditionally Approved [ ] Rejected

Required Actions (if any)

1. ---

2. ---

3. ---

Final Approval

• All critical security requirements met
• All red flags addressed or justified
• Security documentation complete
• Testing completed successfully

Reviewer Signature: ________________ Date: ________________

---

This checklist should be completed for every new add-on and major security-related changes to existing add-ons. Keep this document updated as security requirements evolve.