{"id":19096485,"url":"https://github.com/falon/dmarc-assistant","last_synced_at":"2025-04-30T14:11:40.474Z","repository":{"id":91572482,"uuid":"74455860","full_name":"falon/dmarc-assistant","owner":"falon","description":"A DMARC Management System","archived":false,"fork":false,"pushed_at":"2021-06-25T13:05:01.000Z","size":249,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-19T03:35:38.298Z","etag":null,"topics":["dkim","dkim-keys","dmarc","dmarc-assistant","dmarc-record","opendkim","spf"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/falon.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2016-11-22T09:23:24.000Z","updated_at":"2023-05-19T16:21:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"f7e885d5-9f17-4960-9bc6-c7afec33de61","html_url":"https://github.com/falon/dmarc-assistant","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falon%2Fdmarc-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falon%2Fdmarc-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falon%2Fdmarc-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falon%2Fdmarc-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/falon","download_url":"https://codeload.github.com/falon/dmarc-assistant/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251717726,"owners_count":21632345,"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":["dkim","dkim-keys","dmarc","dmarc-assistant","dmarc-record","opendkim","spf"],"created_at":"2024-11-09T03:36:51.454Z","updated_at":"2025-04-30T14:11:40.446Z","avatar_url":"https://github.com/falon.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DMARC Assistant\n\nThis is a tool written in PHP to manage SPF, DKIM and DMARC setup in multidomain environment.\n\n## Abstract\nDMARC Assistant offers a setup manager for SPF, DKIM and DMARC record using predefined templates. It adds the records to your nameservers.\n\nIt also maintains the DKIM keys (SigningTable and KeyTable, **OpenDKIM required**), and it periodically renews them, keeping old ones for a while.\n\nDMARC Assistant tries to govern your setup and it warns about anomalies.\nEvery activity is tracked via syslog.\n\n## DKIM model\nYou can have different SMTP servers, each signing with different selectors and keys.\n\nDMARC Assistant creates selector and keys for you, and it writes the DNS record on your nameservers. \n\nWe define multiple **Selector Class**, which are a prefix for each selector associated to particular servers set.\nThen we build selector as `\u003cselector class\u003e-\u003chash\u003e`\nThe hash depends on:\n\n- FQDN domain name\n- time slot\n\nThe time slot is defined in `[selector][scheme][period]` of _dkim.conf_ and can be yearly, montly or weekly.\nAt the end of this period the keys are replaced by a new pair.\n\nWhen a pair of key has replaced, the old public key is maintained for a `[delay time][interval]` to allow validation of any deferred mails.\n\nYou can setup any subdomains which sign with parent domain keys and they have an own **AUID**.\nYou can also set an AUID for a single email address.\n\nOf course, to be DMARC friendly, every domain must have at least a dedicated pair of key. Subdomains could use the parent domain keys in relaxed DMARC fashion.\n\n![DKIM model](doc/DMARCAssistant.gif)\n\n## Prerequisites:\n\n1. You are a domain DNS manager and a mail provider for one or multiple domains.\n2. Sign your mails with **OpenDKIM** with *SigningTable* and *KeyTable* over LDAP\n\n## Requisite:\n\n1. PHP 5.5 or greather. Suggested PHP 7.\n2. php-ldap.\n3. php-mysql, only if you configure MySQL driver for delayed delete.\n4. nsupdate\n\t- install it with __yum install bind-utils__.\n\t- grant IP access via nspudate to nameservers.\n5. a local installed OpenDKIM with at least *opendkim-genkey* and a default running config. The OpenDKIMs used by your SMTP server can be different from this one.\n6. web server - Apache HTTPD has been tested - with SSL and authenticated access.\n7. DNS Server configured to be accessed by nsupdate (IP acl).\n8. LDAP Server with\n\t- track modification operational attributes enabled.\n\t- Class of Service supported.\n\n\n## Install:\n\n1. Add the schema _doc/96opendkim.ldif_ to your LDAP Directory server.\nThis schema is a modified version of standard OpenDKIM LDAP schema, with only **DKIMSelector** attribute mandatory.\n\n2. Initialize a new tree on your LDAP server using _doc/dkim\\_initialize.ldif_.\nEnter this file and change any password, password policy references and selector class.\n\n3. Set **date.timezone** in _php.ini_ to ensure work of timing functions.\n\n4. Suggested LDAP indexes:\n\t- cn: equality, presence, substring\n\t- dkimDomain: presence\n\t- dkimIdentity: presence\n\t- dkimKey: presence\n\t- mail: equality, presence\n\t- mailAlternateAddress: equality\n\t- dkimRecord: presence\n\t- ou: presence\n\t- uid: presence\n\n5. Setup your HTTP Server with SSL and authenticated access.\nFor instance, if you have Apache HTTPD Server:\n\t- __yum install httpd mod_ssl__\n\t- vi _/etc/httpd/conf.d/90access.conf_:\n\t```\t\n\t\t\u003cAuthnProviderAlias ldap authservice\u003e\n\t\t   AuthLDAPBindDN uid=proxy,c=en\n\t\t   AuthLDAPBindPassword ******\n\t\t   AuthLDAPURL ldap://localhost:389/c=en?uid\n\t\t\u003c/AuthnProviderAlias\u003e\n    \n\t\t\u003cAuthzProviderAlias ldap-group serviceUsers cn=groupaccess,c=en\u003e\n\t\t\tAuthLDAPBindDN uid=proxy,c=en\n\t\t\tAuthLDAPBindPassword *******\n\t\t\tAuthLDAPURL ldap://localhost:389/c=en?uid\n\t\t\u003c/AuthzProviderAlias\u003e\n    \n\t\t\u003cDirectory /var/www/html/dmarcsetup\u003e\n\t\t\tOptions FollowSymLinks\n\t\t\tAllowOverride None\n\t\t\tAuthBasicProvider authservice\n\t\t\tAuthName \"Welcome on DMARC Assistant\"\n\t\t\tAuthType basic\n\t\t\t\u003cRequireAny\u003e\n\t\t\t\tRequire serviceUsers\n\t\t\t\u003c/RequireAny\u003e\n\t\t\u003c/Directory\u003e\n\t```\t\n\n6. Clone, then from the home directory \n`composer require jeremykendall/php-domain-parser`\n\n   `cp -p getPublicSuffixList.sh /usr/local/bin`\n\n   `chmod 700 /usr/local/bin/getPublicSuffixList.sh`\n\n   Install a systemd timer for Public Suffix List update once a month. This is needed until we provide a new Storage method.\n\n   _/usr/lib/systemd/system/dmarcAssistPSL.service_:\n\n   ```\n   ### Public Suffix Domains Updates ###\n   #\n   # Get latest TLD name for php-domain-parser\n\n   [Unit]\n   Description=Public Suffix Domains Update\n\n   [Service]\n   User=root\n   ExecStart=/usr/local/bin/getPublicSuffixList.sh\n   ```\n\n   _/usr/lib/systemd/system/dmarcAssistPSL.timer_:\n   ```\n   ### Public  Suffix List update timer ###\n   #\n\n   [Unit]\n   Description=Public Suffix List Update timer\n   After=syslog.target network.target\n\n   [Timer]\n   OnCalendar=monthly\n\n   [Install]\n   WantedBy=httpd.service\n   ```\n\n7. The root folder has to be owned by the system user running the web server.\nFor instance:\n```\nchown apache dmarc-setup-assistant\n```\n8. `cp -p ldap.conf_default ldap.conf` and configure it as expected in _dkim\\_initialize.ldif_. Also, set username and password to bind.\n\t- The [delaydel] section is meaningful only if you set `ldap =  TRUE` in `[delay driver]` of *dkim.conf*.\n9. `cp -p dkim.conf_default dkim.conf` and configure it as expected in _dkim\\_initialize.ldif_. In particular, you may want to change the Selector Classes and time slot.\n\t- pay attention. If you change a Selector class, you must manually update the LDIF file _dkim\\_initialize.ldif_ accordingly. For instance, if you add the Selector Class \"alice\", the you must add on the LDAP server:\n```\n\t\tdn: ou=alice,o=dkim\n\t\tou: alice\n\t\tobjectClass: top\n\t\tobjectClass: organizationalunit\n```\n10. `cp -p db.conf_default db.conf` only if you want delay driver over mysql. Set credential, table and field names.\n11. `cp -p dmarc.conf_default dmarc.conf`. This file comes with default RFC7489 values which are not written to the DMARC record. Usually, there are no reasons to modify this file.\n12. `cp -p ns.conf_default ns.conf`.\n\t- Insert in `ns[]` the authotitative name servers of your domains.\n\t- Insert in `[nsupdate][name]` the nameservers \"internal\" and or \"external\" where nsupdate write to. You can set only \"internal\", \"external\" or both. If you set both servers, DMARC Assistant try to write the same record to \"internal\" server and to \"external\" server too.\n13. `cp -p system.conf_default system.conf`. Configure some detail about syslog and path of *opendkim-genkey*. Also set the default SPF and DMARC records.\n\t1. If `template = FALSE` the GUI provides the ability to directly write the record. This could be dangerous.\n\t2. If `template = TRUE` the GUI provides a standard template within you can write the record.\n14. `cp -p spf_config.php_default spf_config.php`. While we don't suggest to modify `$qualifiers` array, you probably must arrange the `$modifiers`. This last one is an array of SPF modifiers which will appear in SPF template. For instance, if you add a modifier like `include:_spfbulk.example.com`, then is your cure to provide a DNS record for that.\n15. Enter the web site and click on Info link on the right upper corner. Check at your setup.\n\t- For your convenience, you could erase the file setup.php after you checked the info provided. Or you could change the permission to 000 (`chmod 000 setup.php`).\n\n## Scheduling\nYou must schedule two operations:\n\n1. DKIM Delayed del keys. Public DKIM keys no longer in use, but still existing to permit verification.\n2. DKIM Keys Renewal task\n\n### DKIM Delayed Del\nThis task is performed by *DKIMDeleteRecord.php*. It returns 0 if no errors occur.\nYou could use this timer:\n\n*dmarcAssistDelkey.timer*\n\n    ### DKIM Delayed Keys removal timer ###\n    #\n    # DMARCAssistant automatically delete your DKIM delayed deleted keys\n    \n    [Unit]\n    Description=DKIM Delayed Deleted Keys removal timer\n    After=syslog.target network.target\n    \n    [Timer]\n    OnCalendar=daily\n    \n    [Install]\n    WantedBy=httpd.service\n\n*dmarcAssistDelkey.service*\n\n    ### DKIM Delayed Keys Removal ###\n    #\n    \n    [Unit]\n    Description=DKIM Delayed Public Keys Delete Service\n    After=syslog.target network.target\n    \n    [Service]\n    User=root\n    ExecStart=/var/www/html/dmarcsetup/DKIMDeleteRecord.php\n    SuccessExitStatus=0\n\n### DKIM Keys Renewal task\nThis task is performed by *DKIMtimer.php*. To ensure starting after the time slot change, the script waits randomly from five minutes to an hours before renew the keys. In this way you can use this timer:\n\n*dmarcAssistRenkey.timer*\n\n    ### DKIM Keys update timer ###\n    #\n    # DMARCAssistant automatically updates your DKIM active keys\n    \n    [Unit]\n    Description=DKIM Keys Update timer\n    After=syslog.target network.target\n    \n    [Timer]\n    OnCalendar=weekly\n    \n    [Install]\n    WantedBy=httpd.service\n\n*dmarcAssistRenkey.service*\n\n    ### DKIM Keys Renew ###\n    #\n    \n    [Unit]\n    Description=DKIM Keys Update Service\n    After=syslog.target network.target\n    \n    [Service]\n    User=root\n    ExecStart=/var/www/html/dmarcsetup/DKIMtimer.php\n    SuccessExitStatus=0\n\nYou are free to use crontab instead. You could be interested to remember that \"weekly\" timer is not synchronized to \"weekly\" crontab ;-)\n\n## GUI Usage:\n\nYou can:\n\n1. Setup initial SPF record\n2. Setup initial DKIM record, keys and selectors\n3. Setup inizial DMARC record\n4. Change SPF and DMARC records\n5. About DKIM you can:\n\t1. manage Selector Classes\n\t2. manage subdomains which sign using parent domain keys\n\t3. manage AUIDs associated to a single email addresses.\n\t4. check the state of keys in current time slot.\n\t5. check setup anomalies\n\t\n![screenshot](doc/screenshot.jpg)\n\n----------\n\n### Setup Operation Mode\n\nDMARC Assistant offers two setup mode:\n\n1. Relaxed\n2. Strict\n\n*Relaxed mode* (default) is the easiest way if you have many subdomain and you want to manage them with one DKIM signature, one DMARC record with relaxed DKIM alignment. If you enter a subdomain, the GUI shows the corresponding Organizational domain for DKIM and DMARC and you can't manage subdomains (with the exception of SPF).\n\n*Strict mode* let you to manage DKIM, DMARC and SPF record for each subdomain. This is the more flexible way. It is useful only if:\n\n1. you want different signatures for each subdomain of the same Organizational domain.\n2. you choose strict DKIM alignment in DMARC policy, so see at above.\n3. you want deeply customize DMARC records for each subdomain.\n\nRemember that with Strict setup mode you could suffer managing your domains. You could really complicate your life! You could fall in disgrace, remember this.\n\n#### Disclaimer ####\nYou find here **only a minimal description**. A more detailed documentation will come... soon...\n\nUse with care, at your own risk.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalon%2Fdmarc-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffalon%2Fdmarc-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalon%2Fdmarc-assistant/lists"}