Skip to main content
  1. All Posts/

dmarcts-report-viewer

Tools PHP

dmarcts-report-viewer

A PHP viewer for DMARC records that have been parsed by John Levine’s rddmarc script or the dmarcts-report-parser.pl into a MySQL or PostgreSQL database.

Features

  • View a table of parsed reports
  • Easily identify potential DMARC related issues through red, orange, yellow and green icons
  • Filter report list by DMARC result, month, domain and reporting organization
  • Sort report list table by any column
  • View DKIM/SPF details for each report in a table, with the same red/orange/yellow/green colour-coding
  • Sort report detail table by any column
  • View the raw XML of the report beside the report detail table
  • Uses AJAX calls to the database; no external Javascript libraries are needed

Screenshots

Screenshot: Initial Report Listing


Larger version

Screenshot: Report Detail


Larger version

Screenshot: Report Detail with Raw XML


Larger version

Installation and Configuration

Requirements

  • A MySQL or PostgreSQL database populated with data from techsneeze.com’s dmarcts-report-parser.pl script or John Levine’s rddmarc script.
  • A working webserver (apache, nginx, …) with PHP
  • Installed php-mysql or php-pgsql and php-xml

Download dmarcts-report-viewer:

git clone https://github.com/techsneeze/dmarcts-report-viewer.git

Configuration

Ensure that all the files are in their own sub-folder.

dmarcts-report-viewer-config.php

Copy dmarcts-report-viewer-config.php.sample to dmarcts-report-viewer-config.php.

cp dmarcts-report-viewer-config.php.sample dmarcts-report-viewer-config.php

Next, edit these basic configuration options near the top of the dmarcts-report-viewer-config.php file with your specific information:

// Supported types: mysql, pgsql. If unset, defaults to mysql
//$dbtype="mysql";
$dbhost="localhost";
$dbname="<dmarc-database-name>";
$dbuser="<dmarc-database-username>";
$dbpass="<password-for-dmarc-database-username>";
$dbport="3306";

$cssfile="default.css";

$default_hostlookup = 1;  // Hostname resolution: 1=on 0=off (Turning off host lookup greatly speeds up the program in the case of mail servers that have ceased to exist)
$default_sort = 1;  // Report listing Start Date: 1=ASCdending 0=DESCending (ASCending is default behaviour )

dmarcts-report-viewer-js

Finally, edit these basic configuration options near the top of the dmarcts-report-viewer.js file with your preferences:

var default_reportlist_height = 60;  // Main Report List height as a percentage of 
                                     // browser window height (without the % mark)

Usage

Navigate in your browser to the location of the dmarcts-report-viewer.php file.
You should be presented with the basic Report List view, allowing you to navigate through the reports that have been parsed.

Icon Color Legend

  • Green : Both DKIM and SPF = pass
  • Red : Both DKIM and SPF = fail
  • Orange : Either DKIM or SPF (but not both) = fail
  • Yellow : Some other condition, and should be investigated (e.g. DKIM or SPF result are missing, “softfail”, “temperror”, etc.)

Option Bar

At the top of the page you will find the option bar where you can set:

  1. Hostname on/off: This determines whether or not the IP address of the mailserver is resolved into a hostname in the Report Detail.
    Hostname resolution is fine until an IP address no longer has a reverse DNS entry (as when a mail server is de-commissioned) and it takes an excessive amount of time before the DNS resolution times out. If this is the case, you can turn off hostname resolution.
  2. Filter Controls:

    • DMARC Result: Filter by the combined result of DKIM/SPF: pass/pass, fail/fail, pass or fail, other condition
    • Month: Filter by any month of reports
    • Domain(s): Filter by any domain
    • Reporter(s): Filter by any reporting organization
    <p>
      If the filter returns no reports, an error message will inform you that no reports meet the criteria you have set. In this case, you can change the filter settings or click on the Reset button to clear the filter. </li> 
      
      <li>
        Buttons</p> <ul dir="auto">
          <li>
            Refresh: This will refresh the data in the Report List while maintaining the currently set filter.
          </li>
          <li>
            Reset: This will reset the filter to show all reports in the Report List and then refresh the data.
          </li>
        </ul>
      </li></ol> 
      
      <h3 dir="auto">
        <a rel="nofollow noopener" target="_blank" id="user-content-report-list" class="anchor" aria-hidden="true" href="#report-list"></a>Report List
      </h3>
      
      <p>
        The Report List table displays all the parsed DMARC reports, initially sorted by Start Date (whether initially ascending or descending is determined by the <code>$default_hostlookup</code> option in <code>dmarcts-report-viewer-config.php</code>) and initially filtered to show only those reports from the latest month available.<br /> Clicking on a column heading will toggle the sort direction of the Report List table by that column. Clicking on any line of the Report List will display the detailed DMARC information of the selected report below the Report List table.
      </p>
      
      <h3 dir="auto">
        <a rel="nofollow noopener" target="_blank" id="user-content-report-detail" class="anchor" aria-hidden="true" href="#report-detail"></a>Report Detail
      </h3>
      
      <p>
        The Report Detail table displays the details of the selected DMARC report, initially sorted by IP Address ascending.<br /> Clicking on a column heading will toggle the sort direction of the Report Detail table by that column.
      </p>
      
      <h3 dir="auto">
        <a rel="nofollow noopener" target="_blank" id="user-content-raw-report-xml" class="anchor" aria-hidden="true" href="#raw-report-xml"></a>Raw Report XML
      </h3>
      
      <p>
        Clicking on the XML icon <a rel="nofollow noopener" target="_blank" href="https://camo.githubusercontent.com/cb69c8fa8adfd6b2f42542acf7b15e274df9fbfb1752b98060eabebba937b481/687474703a2f2f7777772e74656368736e65657a652e636f6d2f77702d636f6e74656e742f75706c6f6164732f323032302f30372f786d6c2e706e67"></a> will display the raw XML of the currently displayed report. Clicking on the HTML icon <a rel="nofollow noopener" target="_blank" href="https://camo.githubusercontent.com/f112d325dee44e4093f3414f5d683405e61c30695717effdb3ce1900abe02816/687474703a2f2f7777772e74656368736e65657a652e636f6d2f77702d636f6e74656e742f75706c6f6164732f323032302f30372f68746d6c2e706e67"></a> will hide the raw XML report.<br /> More info can currently be found at : <a rel="nofollow noopener" target="_blank" href="http://www.techsneeze.com/dmarc-report/">TechSneeze.com</a>
      </p>