Merge pull request #5 from opus-codium/doc

Improve usability

.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

README.md

@@ -1,6 +1,6 @@
 # email-report-processor
 
-A tool to submit e-mail reports into OpenSearch.
+A tool to submit e-mail reports (DMARC, SMTP TLS) into OpenSearch.
 
 > [!CAUTION]
 > This is work-in-progress, expect things to change.
@@ -18,9 +18,10 @@ echo "| email-report-processor" > ~reports/.forward
 
 Alternatively check mail headers, set filters and pipe messages using your preferred tooling.
 
-### DMARC Reporting
+### DMARC Aggregate Reports
 
-Reports SPF / DKIM results when receiving mail from your domain.
+DMARC aggregate feedback reports are defined in [RFC7489, section 7.2](https://datatracker.ietf.org/doc/html/rfc7489#section-7.2).
+They include information about SPF and DKIM check results for e-mail you send.
 
 #### Configuration
 
@@ -85,7 +86,8 @@ PUT /dmarc-reports
 
 ### SMTP TLS Reporting
 
-Reports about TLS usage when contacting your mail server.
+SMTP TLS reports are defined in [RFC8460](https://datatracker.ietf.org/doc/html/rfc8460).
+They include information about cryptography usage for mail you receive.
 
 #### Configuration
 
@@ -118,31 +120,3 @@ PUT /tls-reports
   }
 }
 ```
-
-### MTA-STS Reporting
-
-HSTS for SMTP: Indicate that a given server support Encrypted SMTP and STARTTLS MUST be used when talking to it.
-
-> [!NOTE]
-> Not supported ATM
-
-
-#### Configuration
-
-```
-_mta-sts.blogreen.org.	10800	IN	TXT	"v=STSv1; id=2019020100"
-```
-
-## References
-
-DMARC reports
-https://support.google.com/a/answer/10032472?hl=en
-
-4. Turn on MTA-STS and TLS reporting
-https://support.google.com/a/answer/9276512?hl=en
-
-SMTP MTA Strict Transport Security (MTA-STS)
-https://www.rfc-editor.org/rfc/rfc8461.txt
-
-Introducing MTA Strict Transport Security (MTA-STS)
-https://www.hardenize.com/blog/mta-sts

exe/email-report-processor

@@ -8,16 +8,34 @@ require 'optparse'
 options = {
   class: nil,
   mbox:  false,
+  os:    {},
 }
 
 OptionParser.new do |opts|
-  opts.on('--dmarc') do
+  opts.banner = "usage: #{$PROGRAM_NAME} [options] [file...]"
+  opts.separator("\nReport type selection:")
+  opts.on('--dmarc', 'Process DMARC Reports') do
     options[:class] = EmailReportProcessor::DmarcRua
   end
-  opts.on('--tlsrpt') do
+  opts.on('--tlsrpt', 'Process SMTP TLS Reports') do
     options[:class] = EmailReportProcessor::TlsrptRua
   end
-  opts.on('--mbox') do
+  opts.separator("\nOpenSearch options:")
+  opts.on('-h', '--os-hostname=HOSTNAME', 'Hostname of the OpenSearch instance') do |hostname|
+    options[:os][:hostname] = hostname
+  end
+  opts.on('-p', '--os-port=PORT', 'Port of the OpenSearch instance') do |port|
+    options[:os][:port] = port.to_i
+  end
+  opts.on('-u', '--os-username=USERNAME', 'Username of the OpenSearch instance') do |username|
+    options[:os][:username] = username
+  end
+  opts.on('--os-password=PASSWORD', 'Password of the OpenSearch instance') do |password|
+    options[:os][:password] = password
+  end
+
+  opts.separator("\nMiscellaneous options:")
+  opts.on('--mbox', 'Treat the provided file as a mailbox') do
     options[:mbox] = true
   end
 end.parse!
@@ -27,7 +45,7 @@ if options[:class].nil?
   exit 1
 end
 
-processor = options[:class].new
+processor = options[:class].new(**options[:os])
 
 if ARGV.empty?
   mail = Mail.new($stdin.read)

lib/email_report_processor/base.rb

@@ -11,8 +11,8 @@ module EmailReportProcessor
   class Base
     attr_reader :http, :uri
 
-    def initialize(uri)
-      @uri = uri
+    def initialize(endpoint:, username: 'admin', password: 'admin', hostname: 'localhost', port: 9200)
+      @uri = URI("https://#{username}:#{password}@#{hostname}:#{port}#{endpoint}/_doc")
       @http = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_NONE)
     end
 

lib/email_report_processor/dmarc_rua.rb

@@ -8,8 +8,10 @@
 
 module EmailReportProcessor
   class DmarcRua < Base
-    def initialize
-      super(URI('https://admin:admin@localhost:9200/dmarc-reports/_doc'))
+    DEFAULT_ENDPOINT = '/dmarc-reports'
+
+    def initialize(**options)
+      super(**options, endpoint: options[:dmarc_endpoint] || DEFAULT_ENDPOINT)
     end
 
     def report(raw_report)

lib/email_report_processor/tlsrpt_rua.rb

@@ -6,8 +6,10 @@
 
 module EmailReportProcessor
   class TlsrptRua < Base
-    def initialize
-      super(URI('https://admin:admin@localhost:9200/tls-reports/_doc'))
+    DEFAULT_ENDPOINT = '/tlsrpt-reports'
+
+    def initialize(**options)
+      super(**options, endpoint: options[:tlsrpt_endpoint] || DEFAULT_ENDPOINT)
     end
 
     def report(raw_report)

spec/email_report_processor/base_spec.rb

@@ -6,7 +6,7 @@
 require 'webrick/https'
 
 RSpec.describe EmailReportProcessor::Base do
-  subject(:processor) { described_class.new(URI('https://localhost:9200/')) }
+  subject(:processor) { described_class.new(endpoint: '/endpoint') }
 
   before do
     allow(processor).to receive(:report)