{"id":27078758,"url":"https://github.com/captainpragmatic/mail-sentinel","last_synced_at":"2026-05-19T04:38:10.659Z","repository":{"id":286176592,"uuid":"960614270","full_name":"captainpragmatic/MAIL-Sentinel","owner":"captainpragmatic","description":"My Artificial Intelligence Log Sentinel for Postfix and beyond...","archived":false,"fork":false,"pushed_at":"2025-04-07T20:23:18.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T20:17:56.603Z","etag":null,"topics":["ai-recommendations","bash","bash-script","email-monitoring","gpt-integration","log-analysis","log-management","log-monitoring","mail-server","monitoring-tools","openai-api","postfix","server-monitoring","shell-script","system-administration"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/captainpragmatic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-04T18:34:46.000Z","updated_at":"2025-04-07T20:23:21.000Z","dependencies_parsed_at":"2025-04-04T19:58:27.717Z","dependency_job_id":"e07360ec-1e31-46ee-b576-d19a41a93041","html_url":"https://github.com/captainpragmatic/MAIL-Sentinel","commit_stats":null,"previous_names":["captainpragmatic/m.a.i.l-sentinel"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainpragmatic%2FMAIL-Sentinel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainpragmatic%2FMAIL-Sentinel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainpragmatic%2FMAIL-Sentinel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainpragmatic%2FMAIL-Sentinel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/captainpragmatic","download_url":"https://codeload.github.com/captainpragmatic/MAIL-Sentinel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103906,"owners_count":21048246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-recommendations","bash","bash-script","email-monitoring","gpt-integration","log-analysis","log-management","log-monitoring","mail-server","monitoring-tools","openai-api","postfix","server-monitoring","shell-script","system-administration"],"created_at":"2025-04-06T01:17:53.774Z","updated_at":"2026-05-19T04:38:10.654Z","avatar_url":"https://github.com/captainpragmatic.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ✨ M.A.I.L. Sentinel – My Artificial Intelligence Log Sentinel ✨\n\nM.A.I.L. Sentinel is not just a log monitoring script; it's an intelligent guardian created to scan, filter, and analyze Postfix log data. Inspired by the need for a smarter, self-aware sentinel over your email logs, M.A.I.L. Sentinel leverages AI to provide actionable recommendations for error resolution, ensuring your email infrastructure remains robust and secure.\n\n## 🎯 Key Features\n\n- **🤖 AI-Powered Analysis**: Uses OpenAI to generate actionable recommendations for recurring errors\n- **📊 Executive Summary**: Get an at-a-glance view of critical, warning, and informational issues\n- **🎨 Beautiful HTML Reports**: Modern, responsive email reports with color-coded severity levels\n- **🔍 IP Intelligence**: Automatic hostname, ASN, and country lookup for error sources\n- **⚡ Copy-Paste Commands**: Ready-to-run commands for investigating and fixing issues\n- **📌 Decision Guides**: Step-by-step guidance for common error types\n- **✅ Action Checklists**: Clear next steps for each error category\n- **🎚️ Severity Classification**: Automatic categorization (Critical/Warning/Info)\n- **🔇 Smart Noise Filtering**: Configurable whitelisting of known safe patterns\n- **⚙️ Fully Configurable**: Customizable thresholds, API limits, and time windows\n\n## Requirements ✅\n\n- Bash shell\n- Command line utilities: jq, curl, tac, mail, sendmail, awk, sed.\n- Environment variables:\n  - `POSTFIX_REPORT_EMAIL`: Recipient email address ✉️.\n  - `OPENAI_API_KEY`: Valid OpenAI API key 🔑.\n\n## Configuration ⚙️\n\nCreate a secure configuration file (`config.sh`) in the project directory with your environment variables. You can copy `config.sh.example` as a starting point:\n\n```bash\ncp config.sh.example config.sh\nchmod 600 config.sh\n```\n\n### Required Configuration\n\n```bash\nexport POSTFIX_REPORT_EMAIL=\"user@example.com\"  # Recipient email ✉️\nexport OPENAI_API_KEY=\"your_secure_openai_api_key\"  # API key 🔑\n```\n\n### Optional Configuration (with defaults)\n\n```bash\n# Thresholds and Limits\nexport ERROR_THRESHOLD=5           # Min error count before sending to OpenAI (default: 5)\nexport API_CALL_LIMIT=5           # Max API calls per execution (default: 5)\nexport TIME_WINDOW_HOURS=24       # Hours of logs to analyze (default: 24)\nexport MAX_API_TIMEOUT=30         # OpenAI API timeout in seconds (default: 30)\nexport AUTO_IGNORE_THRESHOLD=3    # Ignore IPs with fewer errors (default: 3)\n\n# Debug Mode\nexport MAIL_SENTINEL_DEBUG=false  # Set to true for verbose output\n\n# Known Safe Patterns (pipe-separated, categorized as INFO)\nexport KNOWN_SAFE_PATTERNS=\"gaia.bounces.google.com|amazonses.com|mailgun.net\"\n```\n\n## Usage 🚀\n\n1. **Quick Installation**: Run the interactive installer:\n   ```bash\n   ./install.sh\n   ```\n   This will guide you through configuration and optional cron job setup.\n\n2. **Manual Setup**:\n   - Ensure that `config.sh` exists and has the correct permissions.\n   - Run the script manually:\n   ```bash\n   ./MAIL-Sentinel.sh\n   ```\n\n3. **Scheduled Execution**: To run as a cronjob, add a line similar to:\n   ```cron\n   0 * * * * ~/scripts/MAIL-Sentinel/MAIL-Sentinel.sh\n   ```\n\n## 📧 Report Features\n\nM.A.I.L. Sentinel generates comprehensive HTML email reports with:\n\n### Executive Summary\n- **Severity Counts**: Visual dashboard showing Critical, Warning, and Info issue counts\n- **Recommended Actions**: Prioritized list of what to do first\n- **Quick Overview**: Understand the health of your mail server at a glance\n\n### Detailed Error Cards\nEach error above the threshold gets a detailed card containing:\n\n1. **Severity Badge**: Color-coded (🔴 Critical, 🟡 Warning, 🟢 Info)\n2. **Error Details**: Full error message and occurrence count\n3. **IP Intelligence**:\n   - Hostname lookup\n   - ASN (Autonomous System Number)\n   - Country of origin\n4. **AI Recommendation**: Smart analysis from OpenAI on how to fix the issue\n5. **Decision Guide**: Step-by-step questions to help you decide what action to take\n6. **Actionable Commands**: Copy-paste ready commands to investigate and fix issues\n7. **Action Checklist**: Clear next steps for resolution\n\n### Severity Levels Explained\n\n- **🔴 CRITICAL**: Requires immediate attention (authentication failures, service disruptions, disk full, fatal errors)\n- **🟡 WARNING**: Should be investigated (SSL errors with \u003e10 occurrences, connection issues, bounces)\n- **🟢 INFO**: Normal noise or known safe patterns (low-count errors, whitelisted services like Google Bounces)\n\n## Security Best Practices 🔒\n\n- Do not commit `config.sh` or any files containing sensitive information to version control.\n- Use `.gitignore` to prevent accidental commits of sensitive files.\n- Keep your `config.sh` file permissions set to 600 (readable only by owner).\n- Regularly review and update your `KNOWN_SAFE_PATTERNS` to reduce noise in reports.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptainpragmatic%2Fmail-sentinel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaptainpragmatic%2Fmail-sentinel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptainpragmatic%2Fmail-sentinel/lists"}