|
| 1 | +# /elixir-security |
| 2 | + |
| 3 | +Security scanning for Elixir projects with Elixir-specific improvements. |
| 4 | + |
| 5 | +## Description |
| 6 | + |
| 7 | +The `/elixir-security` command performs comprehensive security scanning on Elixir projects using multiple security tools. It includes Phoenix-specific security analysis, dependency vulnerability checking, and general security best practices enforcement. |
| 8 | + |
| 9 | +## Usage |
| 10 | + |
| 11 | +```bash |
| 12 | +/elixir-security [options] |
| 13 | +``` |
| 14 | + |
| 15 | +## Options |
| 16 | + |
| 17 | +| Option | Description | |
| 18 | +| ------------------- | ----------------------------------------------- | |
| 19 | +| `--format FORMAT` | Output format: `compact`, `detailed`, or `json` | |
| 20 | +| `--verbose`, `-v` | Verbose output | |
| 21 | +| `--quiet`, `-q` | Quiet mode (minimal output) | |
| 22 | +| `--exit` | Exit with non-zero code on any finding | |
| 23 | +| `--exit-on-vuln` | Exit with non-zero code only on vulnerabilities | |
| 24 | +| `--env ENVIRONMENT` | Set Mix environment: `dev`, `test`, or `prod` | |
| 25 | +| `--help`, `-h` | Show help message | |
| 26 | + |
| 27 | +## Security Tools |
| 28 | + |
| 29 | +### Sobelow (Phoenix Security) |
| 30 | + |
| 31 | +Security-focused static analysis for Phoenix applications. |
| 32 | + |
| 33 | +**Checks performed:** |
| 34 | + |
| 35 | +- Configuration security |
| 36 | +- SQL injection vulnerabilities |
| 37 | +- XSS (Cross-site scripting) |
| 38 | +- CSRF protection |
| 39 | +- Clickjacking protection |
| 40 | +- Secure headers |
| 41 | +- Content security policy |
| 42 | + |
| 43 | +**Example:** |
| 44 | + |
| 45 | +```bash |
| 46 | +/elixir-security # Includes Sobelow for Phoenix projects |
| 47 | +``` |
| 48 | + |
| 49 | +### mix_audit (Dependency Security) |
| 50 | + |
| 51 | +Security audit for Mix dependencies. |
| 52 | + |
| 53 | +**Checks performed:** |
| 54 | + |
| 55 | +- Known vulnerabilities in Hex packages |
| 56 | +- Outdated dependencies with security issues |
| 57 | +- CVEs in dependencies |
| 58 | +- Severity assessment |
| 59 | + |
| 60 | +**Example:** |
| 61 | + |
| 62 | +```bash |
| 63 | +/elixir-security --verbose # Shows detailed vulnerability information |
| 64 | +``` |
| 65 | + |
| 66 | +### General Security Checks |
| 67 | + |
| 68 | +Additional security analysis beyond specific tools. |
| 69 | + |
| 70 | +**Checks performed:** |
| 71 | + |
| 72 | +- Hardcoded secrets and credentials |
| 73 | +- Insecure random number generation |
| 74 | +- File inclusion vulnerabilities |
| 75 | +- Command injection risks |
| 76 | +- Configuration security |
| 77 | +- Authentication and authorization issues |
| 78 | + |
| 79 | +## Examples |
| 80 | + |
| 81 | +```bash |
| 82 | +# Run all security scans |
| 83 | +/elixir-security |
| 84 | + |
| 85 | +# Verbose security scan |
| 86 | +/elixir-security --verbose |
| 87 | + |
| 88 | +# Output results as JSON |
| 89 | +/elixir-security --format json |
| 90 | + |
| 91 | +# Exit on any security finding |
| 92 | +/elixir-security --exit |
| 93 | + |
| 94 | +# Exit only on vulnerabilities |
| 95 | +/elixir-security --exit-on-vuln |
| 96 | + |
| 97 | +# Run in production environment |
| 98 | +/elixir-security --env prod |
| 99 | +``` |
| 100 | + |
| 101 | +## Integration |
| 102 | + |
| 103 | +### CI/CD Pipeline |
| 104 | + |
| 105 | +```yaml |
| 106 | +# GitHub Actions example |
| 107 | +- name: Security Scan |
| 108 | + run: /elixir-security --exit-on-vuln |
| 109 | +``` |
| 110 | +
|
| 111 | +### Pre-commit Hook |
| 112 | +
|
| 113 | +```bash |
| 114 | +#!/bin/bash |
| 115 | +# .git/hooks/pre-commit |
| 116 | + |
| 117 | +# Run security scan on Elixir files |
| 118 | +if git diff --cached --name-only | grep -q '\.ex$'; then |
| 119 | + /elixir-security --quiet |
| 120 | + if [ $? -ne 0 ]; then |
| 121 | + echo "Security issues found. Fix before committing." |
| 122 | + exit 1 |
| 123 | + fi |
| 124 | +fi |
| 125 | +``` |
| 126 | + |
| 127 | +### Scheduled Scanning |
| 128 | + |
| 129 | +```bash |
| 130 | +# Daily security scan (add to cron) |
| 131 | +0 2 * * * cd /path/to/project && /elixir-security --quiet --exit-on-vuln |
| 132 | +``` |
| 133 | + |
| 134 | +## Configuration |
| 135 | + |
| 136 | +### Security Tool Configuration |
| 137 | + |
| 138 | +Configure security tools via `/elixir-setup`: |
| 139 | + |
| 140 | +```bash |
| 141 | +/elixir-setup --configure-security |
| 142 | +``` |
| 143 | + |
| 144 | +**Configuration options:** |
| 145 | + |
| 146 | +- Enable/disable specific security checks |
| 147 | +- Set severity thresholds |
| 148 | +- Configure ignore patterns |
| 149 | +- Set custom rules |
| 150 | +- Configure output formats |
| 151 | +- Set exit code behavior |
| 152 | + |
| 153 | +### Ignoring False Positives |
| 154 | + |
| 155 | +Create `.sobelow-ignore` for Sobelow: |
| 156 | + |
| 157 | +```yaml |
| 158 | +# .sobelow-ignore |
| 159 | +- rule: Config.Secrets |
| 160 | + file: config/prod.exs |
| 161 | + line: 15 |
| 162 | + reason: 'This is a test secret for CI' |
| 163 | +``` |
| 164 | +
|
| 165 | +### Custom Security Rules |
| 166 | +
|
| 167 | +Add custom security rules in project configuration: |
| 168 | +
|
| 169 | +```json |
| 170 | +{ |
| 171 | + "elixir": { |
| 172 | + "security": { |
| 173 | + "customRules": [ |
| 174 | + { |
| 175 | + "id": "CUSTOM_001", |
| 176 | + "pattern": "System.get_env\\(\"SECRET_.*\"\\)", |
| 177 | + "message": "Avoid direct secret access", |
| 178 | + "severity": "medium" |
| 179 | + } |
| 180 | + ] |
| 181 | + } |
| 182 | + } |
| 183 | +} |
| 184 | +``` |
| 185 | + |
| 186 | +## Common Security Issues |
| 187 | + |
| 188 | +### Hardcoded Secrets |
| 189 | + |
| 190 | +**Issue:** |
| 191 | + |
| 192 | +```elixir |
| 193 | +# Bad |
| 194 | +config :my_app, api_key: "hardcoded-secret-123" |
| 195 | + |
| 196 | +# Good |
| 197 | +config :my_app, api_key: System.get_env("API_KEY") |
| 198 | +``` |
| 199 | + |
| 200 | +**Fix:** Use environment variables or secret management systems. |
| 201 | + |
| 202 | +### SQL Injection |
| 203 | + |
| 204 | +**Issue:** |
| 205 | + |
| 206 | +```elixir |
| 207 | +# Bad |
| 208 | +query = "SELECT * FROM users WHERE name = '#{user_input}'" |
| 209 | + |
| 210 | +# Good |
| 211 | +query = from u in User, where: u.name == ^user_input |
| 212 | +``` |
| 213 | + |
| 214 | +**Fix:** Use Ecto query syntax with parameter binding. |
| 215 | + |
| 216 | +### XSS Vulnerabilities |
| 217 | + |
| 218 | +**Issue:** |
| 219 | + |
| 220 | +```elixir |
| 221 | +# Bad |
| 222 | +<%= raw(user_content) %> |
| 223 | + |
| 224 | +# Good |
| 225 | +<%= Phoenix.HTML.html_escape(user_content) %> |
| 226 | +``` |
| 227 | + |
| 228 | +**Fix:** Always escape user content in templates. |
| 229 | + |
| 230 | +### Insecure Dependencies |
| 231 | + |
| 232 | +**Issue:** |
| 233 | + |
| 234 | +```elixir |
| 235 | +# mix.exs |
| 236 | +{:vulnerable_package, "~> 1.0"} # Has known CVEs |
| 237 | +``` |
| 238 | + |
| 239 | +**Fix:** |
| 240 | + |
| 241 | +```bash |
| 242 | +# Check for vulnerabilities |
| 243 | +/elixir-security |
| 244 | + |
| 245 | +# Update vulnerable dependencies |
| 246 | +/elixir-deps update vulnerable_package |
| 247 | +``` |
| 248 | + |
| 249 | +## Best Practices |
| 250 | + |
| 251 | +### 1. Regular Scanning |
| 252 | + |
| 253 | +```bash |
| 254 | +# Scan daily in development |
| 255 | +/elixir-security |
| 256 | + |
| 257 | +# Scan before releases |
| 258 | +/elixir-security --env prod --exit |
| 259 | +``` |
| 260 | + |
| 261 | +### 2. Fix Critical Issues First |
| 262 | + |
| 263 | +```bash |
| 264 | +# Show only critical issues |
| 265 | +/elixir-security --format detailed | grep -i "critical" |
| 266 | +``` |
| 267 | + |
| 268 | +### 3. Integrate with CI/CD |
| 269 | + |
| 270 | +- Run security scans on every pull request |
| 271 | +- Block deployment on critical vulnerabilities |
| 272 | +- Generate security reports |
| 273 | + |
| 274 | +### 4. Keep Dependencies Updated |
| 275 | + |
| 276 | +```bash |
| 277 | +# Regular dependency updates |
| 278 | +/elixir-deps update --all |
| 279 | +/elixir-security # Verify no new vulnerabilities |
| 280 | +``` |
| 281 | + |
| 282 | +### 5. Security Training |
| 283 | + |
| 284 | +- Review security scan results with team |
| 285 | +- Document security practices |
| 286 | +- Regular security awareness training |
| 287 | + |
| 288 | +## Exit Codes |
| 289 | + |
| 290 | +| Code | Description | |
| 291 | +| ---- | ---------------------------------- | |
| 292 | +| 0 | Success - No security issues found | |
| 293 | +| 1 | Failure - Security issues found | |
| 294 | +| 2 | Configuration error | |
| 295 | +| 3 | Tool execution error | |
| 296 | + |
| 297 | +## Related Commands |
| 298 | + |
| 299 | +- `/elixir-setup` - Configure security tools |
| 300 | +- `/elixir-deps` - Update vulnerable dependencies |
| 301 | +- `/elixir-lint` - Code quality (includes some security checks) |
| 302 | +- `/elixir-test` - Security testing integration |
| 303 | + |
| 304 | +## Environment Variables |
| 305 | + |
| 306 | +- `MIX_ENV` - Mix environment (affects configuration loading) |
| 307 | +- `ELIXIR_SECURITY_FORMAT` - Default output format |
| 308 | +- `ELIXIR_SECURITY_EXIT_ON` - Default exit behavior |
| 309 | +- `SOBELOW_CONFIG` - Sobelow configuration file |
| 310 | +- `MIX_AUDIT_CONFIG` - mix_audit configuration |
| 311 | + |
| 312 | +## Notes |
| 313 | + |
| 314 | +- Security scanning is environment-aware |
| 315 | +- Phoenix projects get additional security checks |
| 316 | +- False positives can be configured to ignore |
| 317 | +- Critical findings are highlighted in output |
| 318 | +- Recommendations are provided for fixes |
| 319 | +- Regular updates improve detection accuracy |
| 320 | +- Custom rules can be added for project-specific needs |
| 321 | + |
| 322 | +## Resources |
| 323 | + |
| 324 | +- [Sobelow Documentation](https://hexdocs.pm/sobelow) |
| 325 | +- [mix_audit Documentation](https://hexdocs.pm/mix_audit) |
| 326 | +- [Elixir Security Guide](https://hexdocs.pm/phoenix/security.html) |
| 327 | +- [OWASP Top 10 for Elixir](https://owasp.org/www-project-top-ten/) |
0 commit comments