Merge pull request #35 from userjack6880/dev

Dev

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,43 @@
+---
+name: Bug Report
+about: Something isn't working
+title: "[Bug]: "
+labels: bug
+assignees: userjack6880
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Software Version**
+[ ] Version 0 Alpha 8.1
+[ ] Version 0 Alpha 8
+[ ] Other
+
+**Desktop (please complete the following information):**
+ - OS [e.g. macOS]
+ - Browser [e.g. Safari]
+ - Version [e.g. 15.3]
+
+**Server (please complete the following information):**
+- Server OS [e.g. CentOS 7.3]
+- Web Server [e.g. Apache 2.4.52]
+- PHP Version [e.g. 7.4]
+- SQL Variant and Version [e.g. MariaDB 10.2]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/critical_report.md

@@ -0,0 +1,43 @@
+---
+name: Critical Bug Report
+about: Something is critically broken
+title: "[Critical Bug]: "
+labels: critical, bug
+assignees: userjack6880
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Software Version**
+[ ] Version 0 Alpha 8.1
+[ ] Version 0 Alpha 8
+[ ] Other
+
+**Desktop (please complete the following information):**
+ - OS [e.g. macOS]
+ - Browser [e.g. Safari]
+ - Version [e.g. 15.3]
+
+**Server (please complete the following information):**
+- Server OS [e.g. CentOS 7.3]
+- Web Server [e.g. Apache 2.4.52]
+- PHP Version [e.g. 7.4]
+- SQL Variant and Version [e.g. MariaDB 10.2]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/enhancement_request.md

@@ -0,0 +1,11 @@
+---
+name: Enhancement Request
+about: New feature or request
+title: "[Request]: "
+labels: enhancement
+assignees: userjack6880
+
+---
+
+**Describe the bug**
+A clear and concise description of what you want us to consider.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,11 @@
+---
+name: Question
+about: Further information is requested
+title: "[Question]: "
+labels: question, help wanted
+assignees: userjack6880
+
+---
+
+**Describe the bug**
+What do you need help with?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,41 @@
+# Pull Request Template
+
+## Description
+
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+
+Fixes # (issue)
+
+## Type of change
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+## How Has This Been Tested?
+
+Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration
+
+**Test Configuration**:
+* OS:
+* OS Kernel Version:
+* WebServer:
+* WebServer Version:
+* PHP Version:
+* SQL Variant:
+* SQL Version:
+
+## Checklist:
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published in downstream modules
+- [ ] I have checked my code and corrected any misspellings

README.md

@@ -4,17 +4,23 @@ This is Open DMARC Analyzer version 0 alpha-8 (0-α8) by John Bradley (john@syst
 
 Open DMARC Analyzer was written because there didn't seem to be a full-featured self-hosted report analyzer that provided enough details to make heads or tails of a large volume of DMARC reports that come into medium to large-sized organizations. While other solutions required paid subscriptions or have part of it hosted on AWS, Open DMARC Analyzer will run on any webserver that supports PHP 7.4+ and MySQL 15.1+.
 
-# System Requirements
-- http webserver
-- php 7.4+
-- mysql 15.1+ or equivalent
+# Requirements
+- Apache 2 or equivalent
+- PHP 5 (PHP 7 required for phpWhois)
+- PHP PDO
+- MySQL 15.1 or equivalent
+- A database that is pre-populated with data from rrdmarc or dmarcts-report-parser
 
 # Dependencies
 
-## Required - [jsmitty12/phpWhois](https://github.com/jsmitty12/phpWhois/)
-It is highly recommended that you install this package using composer. Instructions are found on the package's git page. This is required, and will replace most GeoIP data if you disable the MaxMind DB reader package.
+One of the following 2 packages are required to be installed.
+
+**[jsmitty12/phpWhois](https://github.com/jsmitty12/phpWhois/)**
+
+It is highly recommended that you install this package using composer. Instructions are found on the package's git page. This is required, and will replace most GeoIP data if you disable the MaxMind DB reader package. This package *will* require PHP 7.
+
+**[MaxMind DB Reader PHP API](https://github.com/maxmind/MaxMind-DB-Reader-php)**
 
-## Optional - [MaxMind DB Reader PHP API](https://github.com/maxmind/MaxMind-DB-Reader-php)
 A note on this dependency - I've tried to write the one refrence to this external project as optional as possible, and it can almost completely be configured from config.php, due to the limitation of php namespace, I haven't come across a way that won't require you to dig deeper into the code if you happen to chose a compatible library to replace this MaxMind one. If you do wish to replace this library with another compatible one, the line in question is located in `includes\functions.php`:
 ```php
 $reader = new MaxMind\Db\Reader(GEO_DB);
@@ -24,17 +30,104 @@ It is highly recommended that you install this package using composer. Instructi
 
 You will also need the GeoLite2 database from MaxMind (or any other compatible DB). It can be obtained from [here](https://dev.maxmind.com/geoip/geoip2/geolite2/). Open DMARC Analyzer makes use of the GeoLite2 City database.
 
-The MaxMind library is not distributed with this project, and is ultimately an optional feature to the project as a whole.
+The MaxMind library is not distributed with this project, and is ultimately an optional feature to the project as a whole, unless you are using PHP 5.
+
+# Setting up Open DMARC Analyzer
+
+Obtaining Open DMARC Analyzer through `git` is probably the easiest way, in addition to doing occasional pulls to get up-to-date versions.
+
+```
+git clone https://github.com/userjack6880/Open-DMARC-Analyzer.git
+```
+
+Optionally, a [zip file of the latest release](https://github.com/userjack6880/Open-DMARC-Analyzer/releases) can be downloaded.
+
+Once downloaded and installed in a desired directory, install either jsmitty12's phpWhois package or the MaxMind DB Reader package through composer. Rename `config.php.pub` to `config.php` and edit the configuration for your environment (see the next section on **Configuration Options** for details). Finally, run `install.php` to create the database view used by this software package.
+
+`install.php` should remove itself and `mysql.sql` once complete. If permissions aren't given, `install.php` may not delete those files. It is recommended to manually delete these.
+
+# Configuration Options
+
+**Database Options**
+```php
+define('DB_HOST', 'localhost');
+define('DB_USER', 'dmarc');
+define('DB_PASS', 'password');
+define('DB_NAME', 'dmarc');
+define('DB_PORT', '3306'); // default port 3306
+```
+
+**Debug Settings**
+```php
+define('DEBUG', 1);
+```
+*Not Currently Used*
+
+**Template Settings**
+```php
+define('TEMPLATE','openda');
+```
+This will load the visual templated located `templates/`. Simply name the directory the template is located in. Do not use a trailing slash.
+
+**Package Loader**
+```php
+define('AUTO_LOADER','vendor/autoload.php');
+```
+Should not need to change this setting unless using a non-standard composer installation.
+
+**GeoIP2 Settings**
+```php
+define('GEO_ENABLE', 1);
+define('GEO_DB', 'includes/geolite2.mmdb');
+```
+Allows you to select between jsmitty12's phpWhois package and the MaxMind DB Reader package. The default is to use the MaxMind DB Reader package, as it provides the most relevant data to the user. To fall back to the jsmitty12's phpWhois package, change the `GEO_ENABLE` option to `0`.
+
+The second option, `GEO_DB` is used in conjunction with the MaxMind DB Reader package. The path to the MaxMind GeoIP database is relative to the root of the software package.
+
+**Date Range**
+```php
+define('DATE_RANGE', '-1w');
+```
+Defines the standard starting date range for data presented. All pages where dates are relevant start at a certain point and end at the time the page is loaded. This option defines where that starting point is, and the increment by which that starting date is changed.
+
+Valid date signifiers are `m`, `w`, and `d` for "month", "week", and "day".
 
 # Latest Changes
 
-## 0-α8
+## 0-α8.1
+
+- Added `CODE_OF_CONDUCT`, `CONTRIBUTING`, pull request template, issue templates, and organized documents into docs folder.
+- Added basic installation script to add `report_stats` view from file and attempt to cleanup after itself.
+- Further fleshed out `README.md`
+- Improved compatibility with older SQL databases that do not support `INET6_ATON` or `INET6_NTOA`. 
+- Added SQL error output.
+
+See `CHANGELOG` under `docs` for full details of all changes.
+
+# Tested System Configurations
+
+| OS        | HTTP          | PHP    | SQL             |
+| --------- | ------------- | ------ | --------------- |
+| Debian 11 | Apache 2.4.52 | 7.4.25 | MariaDB 10.5.12 |
+| CentOS 7  | Apache 2.4.6  | 5.4.16 | MariaDB 5.5.65  |
+
+If you have a system configuration not listed, and would like to contribue this data, please [provide feedback](https://github.com/userjack6880/Open-Dmarc-Analyzer/issues).
+
+# Release Cycle and Versioning
+
+This project regular release cycle is not yet determined. Versioning is under the Anomaly Versioning Scheme (2022), as outlined in `VERSIONING` under `docs`.
+
+# Contributing
+
+Public contributions are encouraged. Please review `CONTRIBUTING` under `docs` for contributing procedures. Additionally, please take a look at our `CODE_OF_CONDUCT`. By participating in this project you agree to abide by the Code of Conduct.
+
+# Contributors
 
-- Rewrite of ODA for performance and visual improvements and feature simplification.
-- Begin Documentation Process
+Primary Contributors
+- John Bradley - Initial Work
 
-See `CHANGELOG.md` for full details of all changes.
+Thanks to [all who contributed](https://github.com/userjack6880/Open-DMARC-Analyzer/graphs/contributors) and [have given feedback](https://github.com/userjack6880/Open-DMARC-Analyzer/issues?q=is%3Aissue).
 
-# License
+# Licenses
 
-Open DMARC Analyzer is released under GNU GPLv3. See LICENSE.
+Open DMARC Analyzer is released under GNU GPLv3. See `LICENSE`.

config.php.pub

@@ -21,7 +21,7 @@ You should have received a copy of the GNU General Public License along with
 this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
-// MySQL Settings
+// Database Settings
 
 define('DB_HOST', 'localhost');
 define('DB_USER', 'dmarc');
@@ -44,7 +44,7 @@ define('AUTO_LOADER', 'vendor/autoload.php');   // autoloader for composer insta
 define('GEO_ENABLE', 1);                        // 0 - disable GeoIP2, 1 - enable GeoIP2
 define('GEO_DB', 'includes/geolite2.mmdb');     // location of GeoIP2 database
 
-// Defaults
+// Date Range
 
 define('DATE_RANGE', '-1w');
 

CHANGELOG.md → docs/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0-α8.1
+
+- Added `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, pull request template, issue templates, and organized documents into docs folder.
+- Added basic installation script to add `report_stats` view from file and attempt to cleanup after itself.
+- Further fleshed out `README.md`
+- Improved compatibility with older SQL databases that do not support `INET6_ATON` or `INET6_NTOA`.
+- Added SQL error output.
+
 ## 0-α8
 
 - Rewrite of ODA for performance and visual improvements and feature simplification.