From d0d386e7ad286e727f4640ea8e061ad61f6d3b5e Mon Sep 17 00:00:00 2001 From: Sean Whalen Date: Mon, 4 Feb 2019 23:59:06 -0500 Subject: [PATCH] Update documentation --- docs/example.ini | 2 +- docs/index.rst | 68 ++++++++++++++++++++++------------------------- parsedmarc/cli.py | 16 +++++------ 3 files changed, 41 insertions(+), 45 deletions(-) diff --git a/docs/example.ini b/docs/example.ini index 7aa68908..5c109181 100644 --- a/docs/example.ini +++ b/docs/example.ini @@ -11,7 +11,7 @@ password = $uperSecure watch = True [elasticsearch] -urls = 127.0.0.1:92000 +hosts = 127.0.0.1:92000 ssl = False [splunk_hec] diff --git a/docs/index.rst b/docs/index.rst index fdfa33b4..7c271831 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -121,7 +121,7 @@ For example watch = True [elasticsearch] - urls = 127.0.0.1:92000 + hosts = 127.0.0.1:92000 ssl = False [splunk_hec] @@ -149,11 +149,39 @@ The full set of configuration options are: - ``user`` - str: The IMAP user - ``password`` - str: The IMAP password - ``reports_folder`` - str: The IMAP folder where the incoming reports can be found (Default: INBOX) - - ``archive_folder`` - str: The IMAP folder to sort processed emails into + - ``archive_folder`` - str: The IMAP folder to sort processed emails into (Default: Archive) - ``watch`` - bool: Use the IMAP ``IDLE`` command to process messages as they arrive - ``delete`` - bool: Delete messages after processing them, instead of archiving them - ``test`` - bool: Do not move or delete messages - +- ``elasticsearch`` + - ``hosts`` - str: A comma separated list of URLs (e.g. https://user:secret@localhost:443) + - ``ssl`` - bool: Use an encrypted SSL/TLS connection (Default: True) + - ``cert_path`` - str: Path to a trusted certificates + - ``index_suffix`` - str: A suffix to apply to the index names + - ``monthly_indexes`` - bool: Use monthly indexes instead of daily indexes +- ``splunk_hec`` + - ``url`` - str: The URL of the Splunk HTTP Events Collector (HEC) + - ``token`` - str: The HEC token + - ``index`` - str: The Splunk index to use + - ``skip_certificate_verification`` - bool: Skip certificate verification (not recommended) +- ``kafka`` + - ``hosts`` - str: A comma separated list of Kafka hosts + - ``user`` - str: The Kafka user + - ``passsword`` - str: The Kafka password + - ``ssl`` - bool: Use an encrypted SSL/TLS connection (Default: True) + - ``aggregate_topic`` - str: The Kafka topic for aggregate reports + - ``forensic_topic`` - str: The Kafka topic for forensic reports +- ``smtp`` + - ``host`` - str: The SMTP hostname + - ``port`` - int: The SMTP port (Default: 25) + - ``ssl`` - bool: Require SSL/TLS instead of using STARTTLS + - ``user`` - str: the SMTP username + - ``password`` - str: the SMTP password + - ``from`` - str: The From header to use in the email + - ``to`` - list: A list of email addresses to send to + - ``subject`` - str: The Subject header to use in the email (Default: parsedmarc report) + - ``attachment`` - str: The ZIP attachment filenames + - ``message`` - str: The email message (Default: Please see the attached parsedmarc report.) Sample aggregate report output ============================== @@ -894,22 +922,7 @@ Splunk ------ Starting in version 4.3.0 ``parsedmarc`` supports sending aggregate and/or -forensic DMARC data to a Splunk `HTTP Event collector (HEC)`_. Simply use the -following command line options, along with ``--save-aggregate`` and/or -``--save-forensic``: - - -:: - - --hec HEC URL to a Splunk HTTP Event Collector (HEC) - --hec-token HEC_TOKEN - The authorization token for a Splunk HTTP Event - Collector (HEC) - --hec-index HEC_INDEX - The index to use when sending events to the Splunk - HTTP Event Collector (HEC) - --hec-skip-certificate-verification - Skip certificate verification for Splunk HEC +forensic DMARC data to a Splunk `HTTP Event collector (HEC)`_. The project repository contains `XML files`_ for premade Splunk dashboards for @@ -964,23 +977,6 @@ Create the service configuration file [Install] WantedBy=multi-user.target -Edit the command line options of ``parsedmarc`` in the service's ``ExecStart`` -setting to suit your needs. - -.. note:: - - Always pass the ``--watch`` option to ``parsedmarc`` when running it as a - service. Use ``--silent`` to only log errors. - -.. warning:: - - As mentioned earlier, forensic/failure reports contain copies of emails - that failed DMARC, including emails that may be legitimate and contain - sensitive customer or business information. For privacy and/or regulatory - reasons, you may not want to use the ``--save-forensic`` flag included in - the example service configuration ``ExecStart`` setting, which would save - these samples to Elasticsearch. - Then, enable the service .. code-block:: bash diff --git a/parsedmarc/cli.py b/parsedmarc/cli.py index f9c1e65d..f18cedc0 100644 --- a/parsedmarc/cli.py +++ b/parsedmarc/cli.py @@ -44,7 +44,7 @@ def _main(): if opts.save_aggregate: for report in reports_["aggregate_reports"]: try: - if opts.elasticsearch_host: + if opts.elasticsearch_hostss: elastic.save_aggregate_report_to_elasticsearch( report, index_suffix=opts.elasticsearch_index_suffix, @@ -72,7 +72,7 @@ def _main(): if opts.save_forensic: for report in reports_["forensic_reports"]: try: - if opts.elasticsearch_host: + if opts.elasticsearch_hostss: elastic.save_forensic_report_to_elasticsearch( report, index_suffix=opts.elasticsearch_index_suffix, @@ -157,7 +157,7 @@ def _main(): hec_token=None, hec_index=None, hec_skip_certificate_verification=False, - elasticsearch_host=None, + elasticsearch_hostss=None, elasticsearch_index_suffix=None, elasticsearch_ssl=True, kafka_hosts=None, @@ -233,7 +233,7 @@ def _main(): if "elasticsearch" in config: elasticsearch_config = config["elasticsearch"] if "hosts" in elasticsearch_config: - opts.elasticsearch_host = _str_to_list(elasticsearch_config[ + opts.elasticsearch_urls = _str_to_list(elasticsearch_config[ "hosts"]) if "index_suffix" in elasticsearch_config: opts.elasticsearch_index_suffix = elasticsearch_config[ @@ -280,8 +280,8 @@ def _main(): opts.smtp_port = smtp_config["port"] if "ssl" in smtp_config: opts.smtp_ssl = smtp_config.getboolean("ssl") - if "username" in smtp_config: - opts.smtp_user = smtp_config["username"] + if "user" in smtp_config: + opts.smtp_user = smtp_config["user"] if "password" in smtp_config: opts.smtp_password = smtp_config["password"] if "from" in smtp_config: @@ -314,7 +314,7 @@ def _main(): if opts.save_aggregate or opts.save_forensic: try: - if opts.elasticsearch_host: + if opts.elasticsearch_hostss: es_aggregate_index = "dmarc_aggregate" es_forensic_index = "dmarc_forensic" if opts.elasticsearch_index_suffix: @@ -323,7 +323,7 @@ def _main(): es_aggregate_index, suffix) es_forensic_index = "{0}_{1}".format( es_forensic_index, suffix) - elastic.set_hosts(opts.elasticsearch_host, + elastic.set_hosts(opts.elasticsearch_hostss, opts.elasticsearch_ssl, opts.elasticsearch_ssl_cert_path) elastic.migrate_indexes(aggregate_indexes=[es_aggregate_index],