{"id":19387710,"url":"https://github.com/haraka/haraka-plugin-bounce","last_synced_at":"2025-07-17T18:31:42.348Z","repository":{"id":237021760,"uuid":"793646187","full_name":"haraka/haraka-plugin-bounce","owner":"haraka","description":"Provide options for Haraka bounce processing","archived":false,"fork":false,"pushed_at":"2025-06-02T16:41:05.000Z","size":54,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-02T17:24:52.155Z","etag":null,"topics":["bounce","haraka","haraka-plugin"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/haraka-plugin-bounce","language":"JavaScript","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/haraka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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,"zenodo":null}},"created_at":"2024-04-29T15:56:00.000Z","updated_at":"2025-06-02T16:40:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"bf4a737a-6388-4574-a2ac-7b441c3daa25","html_url":"https://github.com/haraka/haraka-plugin-bounce","commit_stats":null,"previous_names":["haraka/haraka-plugin-bounce"],"tags_count":5,"template":false,"template_full_name":"haraka/haraka-plugin-template","purl":"pkg:github/haraka/haraka-plugin-bounce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-plugin-bounce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-plugin-bounce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-plugin-bounce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-plugin-bounce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haraka","download_url":"https://codeload.github.com/haraka/haraka-plugin-bounce/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haraka%2Fharaka-plugin-bounce/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265645388,"owners_count":23804183,"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":["bounce","haraka","haraka-plugin"],"created_at":"2024-11-10T10:10:15.386Z","updated_at":"2025-07-17T18:31:42.334Z","avatar_url":"https://github.com/haraka.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI Test Status][ci-img]][ci-url]\n[![Code Climate][clim-img]][clim-url]\n\n# haraka-plugin-bounce\n\nThis plugin provides multiple configurable strategies to detect, validate, and process email bounces, helping protect your mail server from backscatter, forged bounces, and bounce-based attacks.\n\nKey capabilities include:\n\n- Validating bounce message authenticity using cryptographic hashes\n- Filtering based on bounce characteristics (single recipient, return path)\n- SPF validation for bounce messages\n- Configurable whitelist for legitimate null-sender messages\n- Fine-grained rejection controls for each validation method\n\n## Configuration\n\nEach feature can be enabled/disabled with a true/false toggle in the `[validation]`, `[check]`, or `[reject]`sections of `config/bounce.ini`:\n\nSome features can have rejections disabled in the `[reject]` section.\n\nThe hash validation feature will automatically be disabled unless a secret key is created. You can create the secret key by running `openssl rand -base64 32`.\n\n```ini\n[validation]\nmax_hash_age_days=6\nhash_algorithm=sha256\nsecret=\n\n[check]\nsingle_recipient=true\nempty_return_path=false\nbounce_spf=true\nhash_validation=false\nhash_date=true\n\n[reject]\nsingle_recipient=true\nempty_return_path=false\nbounce_spf=false\nhash_date=false\nbad_rcpt=true\nall_bounces=false\nhash_validation=false\nhash_date=false\n```\n\n## Features\n\n### enable_hash\n\nAdds a X-Haraka-Bounce-Validation header to outbound emails to help verify the authenticity of bounce messages. The header contains an HMAC SHA-256 hash created using the message's From, Date, and Message-ID headers, and a configured secret key.\n\nCreate the secret key by running `openssl rand -base64 32` and adding the result to the secret setting in the config file.\n\nThis header is used to verify the authenticity of incoming bounce messages by recreating and comparing the hash. If this is enabled on one server, it should be enabled on all servers.\n\n### hash_algorithm\n\nThe cryptographic algorithm to use for hash generation. The default is sha256. Other algorithms may be supported by Node.js crypto module (run crypto.getHashes() for options)\n\n### secret\n\nA cryptographic secret used for hash generation. Must be at least 32 characters long for adequate security. Create the secret key by running `openssl rand -base64 32` and adding the result to this setting in `config/bounce.ini`.\n**CRITICAL:** Must be kept private and consistent across all mail servers\n\n### single_recipient\n\nValid bounces have a single recipient. Assure that the message really is a bounce by enforcing bounces to be addressed to a single recipient.\n\nThis check is skipped for relays or hosts with a private IP, this is because Microsoft Exchange distribution lists will send messages to list members with a null return-path when the 'Do not send delivery reports' option is enabled (yes, really...).\n\n### empty_return_path\n\nValid bounces should have an empty return path. Test for the presence of the Return-Path header in bounces and disallow.\n\n### bounce_spf\n\nParses the message body and any MIME parts for Received: headers and strips out the IP addresses of each Received hop and then checks what the SPF result would have been if bounced message had been sent by that hop.\n\nIf no 'Pass' result is found, then this test will fail. If SPF returns 'None', 'TempError' or 'PermError' then the test will be skipped.\n\n### hash_date\n\nWhen enabled, verifies that the hash was created within the last config/max_hash_age_days.\n\n### bad_rcpt\n\nWhen enabled, rejects bounces to email addresses listed in `config/bounce_bad_rcpt`.\n\nInclude email addresses that should _never_ receive bounce messages. Examples of email addresses that should be listed are: autoresponders, do-not-reply@example.com, dmarc-feedback@example.com, and any other email addresses used solely for machine generated messages.\n\n### all_bounces\n\nWhen enabled, blocks all bounce messages using the simple rule of checking for `MAIL FROM:\u003c\u003e`.\n\nIt is generally a bad idea to block all bounces. This option can be useful for mail servers at domains with frequent spoofing and few or no human users.\n\n## Whitelist\n\nYou can whitelist emails with null senders by adding the recipient to `config/bounce_whitelist.json` with an array of From email addresses. You can also whitelist the From domain by replacing the user portion with an asterisk, i.e. `*@example.com`.\n\n```json\n{\n  \"test@example.com\": [\"no-reply@example.com\", \"support@example.com\"],\n  \"foo@example.com\": [\"sales@example.com\"],\n  \"bar@example.com\": [\"*@example.net\", \"office@example.com\"]\n}\n```\n\n## INSTALL\n\ncd /path/to/local/haraka\nnpm install haraka-plugin-bounce\necho \"bounce\" \u003e\u003e config/plugins\nservice haraka restart\n\n## USAGE\n\nAdd `bounce` to Haraka's config/plugins file. If desired, install and customize a local bounce.ini.\n\n```sh\ncp node_modules/haraka-plugin-bounce/config/bounce.ini config/bounce.ini\n$EDITOR config/bounce.ini\n```\n\n\u003c!-- leave these buried at the bottom of the document --\u003e\n\n[ci-img]: https://github.com/haraka/haraka-plugin-bounce/actions/workflows/ci.yml/badge.svg\n[ci-url]: https://github.com/haraka/haraka-plugin-bounce/actions/workflows/ci.yml\n[clim-img]: https://codeclimate.com/github/haraka/haraka-plugin-bounce/badges/gpa.svg\n[clim-url]: https://codeclimate.com/github/haraka/haraka-plugin-bounce\n[npm-img]: https://nodei.co/npm/haraka-plugin-bounce.png\n[npm-url]: https://www.npmjs.com/package/haraka-plugin-bounce\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharaka%2Fharaka-plugin-bounce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharaka%2Fharaka-plugin-bounce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharaka%2Fharaka-plugin-bounce/lists"}