From c93ba44ed14e73ee7fc51688aaddf81e4974b8a4 Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sat, 3 Feb 2024 22:36:30 -0500
Subject: [PATCH 01/10] Add `--toml-file` command
---
README.md | 56 ++++++++++++++++++++++++++--------------
eeauditor/cloud_utils.py | 11 +++++---
eeauditor/controller.py | 13 ++++++++--
eeauditor/eeauditor.py | 28 ++++++++++----------
4 files changed, 68 insertions(+), 40 deletions(-)
diff --git a/README.md b/README.md
index db0827f2..65304472 100644
--- a/README.md
+++ b/README.md
@@ -65,45 +65,51 @@ ElectricEye also uses utilizes other tools such as [Shodan.io](https://www.shoda
1. First, clone this repository and install the requirements using `pip3`: `pip3 install -r requirements.txt`.
-2. Then, modify the [TOML configuration](./eeauditor/external_providers.toml) located in `ElectricEye/eeauditor/external_providers.toml` to specify various configurations for the CSP(s) and SaaS Provider(s) you want to assess, specify where credentials are stored, and configure Outputs.
+2. If you are evaluating anything other than your local AWS Account, provide a path to a modified [TOML configuration](./eeauditor/external_providers.toml) with `--toml-file` located in `ElectricEye/eeauditor/external_providers.toml`, or modify the example provided and do not provide that argument. The TOML file specifies multi-account, mulit-region, credential, and output specifics.
3. Finally, run the Controller to learn about the various Checks, Auditors, Assessment Targets, and Outputs.
```
-$ python3 eeauditor/controller.py --help
+python3 eeauditor/controller.py --help
Usage: controller.py [OPTIONS]
Options:
- -t, --target-provider [AWS|Azure|OCI|GCP|Servicenow|M365|Salesforce]
+ -t, --target-provider [AWS|Azure|OCI|GCP|Servicenow|M365|Salesforce]
CSP or SaaS Vendor Assessment Target, ensure
- that any -a or -c arg maps to your target
+ that any -a or -c arg maps to your target
provider e.g., -t AWS -a
Amazon_APGIW_Auditor
- -a, --auditor-name TEXT Specify which Auditor you want to run by
- using its name NOT INCLUDING .py. Defaults
+ -a, --auditor-name TEXT Specify which Auditor you want to run by
+ using its name NOT INCLUDING .py. Defaults
to ALL Auditors
- -c, --check-name TEXT A specific Check in a specific Auditor you
+ -c, --check-name TEXT A specific Check in a specific Auditor you
want to run, this correlates to the function
name. Defaults to ALL Checks
- -d, --delay INTEGER Time in seconds to sleep between Auditors
+ -d, --delay INTEGER Time in seconds to sleep between Auditors
being ran, defaults to 0
- -o, --outputs TEXT A list of Outputs (files, APIs, databases,
- ChatOps) to send ElectricEye Findings,
- specify multiple with additional arguments:
- -o csv -o postgresql -o slack [default:
+ -o, --outputs TEXT A list of Outputs (files, APIs, databases,
+ ChatOps) to send ElectricEye Findings,
+ specify multiple with additional arguments:
+ -o csv -o postgresql -o slack [default:
stdout]
- --output-file TEXT For file outputs such as JSON and CSV, the
- name of the file, DO NOT SPECIFY .file_type
+ --output-file TEXT For file outputs such as JSON and CSV, the
+ name of the file, DO NOT SPECIFY .file_type
[default: output]
--list-options Lists all valid Output options
- --list-checks Prints a table of Auditors, Checks, and
- Check descriptions to stdout - use this for
+ --list-checks Prints a table of Auditors, Checks, and
+ Check descriptions to stdout - use this for
-a or -c args
--create-insights Create AWS Security Hub Insights for
ElectricEye. This only needs to be done once
per Account per Region for Security Hub
--list-controls Lists all ElectricEye Controls (e.g. Check
Titles) for an Assessment Target
+ --toml-path TEXT The full path to the TOML file used for
+ configure e.g.,
+ ~/path/to/mydir/external_providers.toml. If
+ this value is not provided the default path
+ of ElectricEye/eeauditor/external_providers.
+ toml is used.
--help Show this message and exit.
```
@@ -169,9 +175,15 @@ To pull from the various repositories, use these commands, you can replace `late
#### NOTE!! You can skip this section if you are using hard-coded credentials in your TOML and if you will not be using any AWS Output or running any AWS Auditors
-When interacting with AWS credential stores such as AWS Systems Manager, AWS Secrets Manager and Outputs such as AWS Security and for Role Assumption into the Role specified in the `aws_electric_eye_iam_role_name` TOML parameter, ElectricEye uses your current (default) Boto3 Session which is derived from your credentials. Running ElectricEye from AWS Infrastructure that has an attached Role, or running from a location with `aws cli` credentials already instantiated, this is handled transparently. When using Docker, you will need to provide [Environment Variables](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables) directly to the Container.
+When interacting with AWS credential stores such as AWS Systems Manager, AWS Secrets Manager and Outputs such as AWS Security and for Role Assumption into the Role specified in the `aws_electric_eye_iam_role_name` TOML parameter, ElectricEye uses your current (default) Boto3 Session which is derived from your credentials.
-Ensure that if you will be using AWS SSM (`ssm:GetParameter`), AWS Secrets Manager (`secretsmanager:GetSecretValue`), AWS Security Hub (`securityhub:BatchImportFindings`), Amazon SQS (`sqs:SendMessage`), and/or Amazon DynamoDB (`dynamodb:PutItem`) for credentials and Outputs that you have the proper permissions! You will likely also require `kms:Decrypt` depending if you are using AWS Key Management Service (KMS) Customer-managed Keys (CMKs) for your secrets/parameters encryption. You will need `sts:AssumeRole` to assume into the Role specified in the `aws_electric_eye_iam_role_name` TOML parameter.
+Running ElectricEye from AWS Infrastructure that has an attached Role, or running from a location with `aws cli` credentials already instantiated, this is handled transparently.
+
+When using Docker, you will need to provide [Environment Variables](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables) directly to the Container.
+
+Ensure that if you will be using AWS SSM (`ssm:GetParameter`), AWS Secrets Manager (`secretsmanager:GetSecretValue`), AWS Security Hub (`securityhub:BatchImportFindings`), Amazon SQS (`sqs:SendMessage`), and/or Amazon DynamoDB (`dynamodb:PutItem`) for credentials and Outputs that you have the proper permissions! You will likely also require `kms:Decrypt` depending if you are using AWS Key Management Service (KMS) Customer-managed Keys (CMKs) for your secrets/parameters encryption.
+
+You will need `sts:AssumeRole` to assume into the Role specified in the `aws_electric_eye_iam_role_name` TOML parameter.
You will need to pass in your AWS Region, an AWS Access Key, and an AWS Secret Access Key. If you are NOT using an AWS IAM User with Access Keys you will need to also provide an AWS Session Token which is produced by temporary credentials such as an IAM Role or EC2 Instance Profile.
@@ -231,7 +243,11 @@ sudo docker run \
electriceye /bin/bash -c "python3 eeauditor/controller.py --help"
```
-To save a local file output such as `-o json`. `-o cam-json`, `-o csv`, or `-o html` and so on, ensure that you specify a file name that begins with `/eeauditor/` as the `eeuser` within the Docker Image only has permissions within that directory. To remove the files you cannot use `docker cp` but you can submit the file to remote APIs you have control of by `base64` encoding the output or you can use the Session with AWS S3 permissions to upload the file to S3. If you are evaluating Oracle Cloud or Google Cloud Platform, your credentials will be locally loaded and you can upload to Oracle Object Storage or Google Cloud Storage buckets, respectively.
+To save a local file output such as `-o json`. `-o cam-json`, `-o csv`, or `-o html` and so on, ensure that you specify a file name that begins with `/eeauditor/` as the `eeuser` within the Docker Image only has permissions within that directory.
+
+To remove the files you cannot use `docker cp` but you can submit the file to remote APIs you have control of by `base64` encoding the output or you can use the Session with AWS S3 permissions to upload the file to S3.
+
+If you are evaluating Oracle Cloud or Google Cloud Platform, your credentials will be locally loaded and you can upload to Oracle Object Storage or Google Cloud Storage buckets, respectively.
```bash
BUCKET_NAME="your_s3_bucket_you_have_access_to"
@@ -272,7 +288,7 @@ Feel free to open PRs and Issues where syntax, grammatic, and implementation err
### ElectricEye is for sale
-Contact the maintainer for more information!
+Hit me up at opensource@electriceye.cloud (I don't actually have a SaaS tool) and I'll gladly sell the rights to this repo and take it down and give you all of the domains and even the AWS Accounts that I use behind the scenes.
### Early Contributors
diff --git a/eeauditor/cloud_utils.py b/eeauditor/cloud_utils.py
index 5903dc0f..c9ebca46 100644
--- a/eeauditor/cloud_utils.py
+++ b/eeauditor/cloud_utils.py
@@ -27,7 +27,7 @@
import json
from botocore.exceptions import ClientError
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("CloudUtils")
# Boto3 Clients
sts = boto3.client("sts")
@@ -45,9 +45,12 @@ class CloudConfig(object):
for use in EEAuditor when running ElectricEye Auditors and Check
"""
- def __init__(self, assessmentTarget):
- here = path.abspath(path.dirname(__file__))
- tomlFile = f"{here}/external_providers.toml"
+ def __init__(self, assessmentTarget, tomlPath):
+ if tomlPath is None:
+ here = path.abspath(path.dirname(__file__))
+ tomlFile = f"{here}/external_providers.toml"
+ else:
+ tomlFile = tomlPath
with open(tomlFile, "rb") as f:
data = tomload(f)
diff --git a/eeauditor/controller.py b/eeauditor/controller.py
index 3e3ce59a..8a543ed0 100644
--- a/eeauditor/controller.py
+++ b/eeauditor/controller.py
@@ -38,11 +38,12 @@ def print_checks(assessmentTarget, auditorName=None):
app.print_checks_md()
-def run_auditor(assessmentTarget, auditorName=None, pluginName=None, delay=0, outputs=None, outputFile=""):
+def run_auditor(assessmentTarget, auditorName=None, pluginName=None, delay=0, outputs=None, outputFile="", tomlPath=None):
if not outputs:
outputs = ["stdout"]
- app = EEAuditor(assessmentTarget)
+ app = EEAuditor(assessmentTarget, tomlPath)
+
app.load_plugins(auditorName)
# Per-target calls - ensure you use the right run_*_checks*() function
if assessmentTarget == "AWS":
@@ -147,6 +148,12 @@ def run_auditor(assessmentTarget, auditorName=None, pluginName=None, delay=0, ou
is_flag=True,
help="Lists all ElectricEye Controls (e.g. Check Titles) for an Assessment Target"
)
+# TOML Path
+@click.option(
+ "--toml-path",
+ default=None,
+ help="The full path to the TOML file used for configure e.g., ~/path/to/mydir/external_providers.toml. If this value is not provided the default path of ElectricEye/eeauditor/external_providers.toml is used."
+)
def main(
target_provider,
@@ -159,6 +166,7 @@ def main(
list_checks,
create_insights,
list_controls,
+ toml_path
):
if list_controls:
print_controls(
@@ -191,6 +199,7 @@ def main(
delay=delay,
outputs=outputs,
outputFile=output_file,
+ tomlPath=toml_path
)
if __name__ == "__main__":
diff --git a/eeauditor/eeauditor.py b/eeauditor/eeauditor.py
index fc8e0e4a..d0244357 100644
--- a/eeauditor/eeauditor.py
+++ b/eeauditor/eeauditor.py
@@ -31,7 +31,7 @@
from cloud_utils import CloudConfig
from pluginbase import PluginBase
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("EEAuditor")
here = path.abspath(path.dirname(__file__))
getPath = partial(path.join, here)
@@ -42,7 +42,7 @@ class EEAuditor(object):
credentials and cross-boundary configurations, and runs Checks and yields results back to controller.py CLI
"""
- def __init__(self, assessmentTarget, searchPath=None):
+ def __init__(self, assessmentTarget, tomlPath=None, searchPath=None):
# each check must be decorated with the @registry.register_check("cache_name")
# to be discovered during plugin loading.
self.registry = CheckRegister()
@@ -54,7 +54,7 @@ def __init__(self, assessmentTarget, searchPath=None):
# AWS
if assessmentTarget == "AWS":
searchPath = "./auditors/aws"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# parse specific values for Assessment Target - these should match 1:1 with CloudConfig
self.awsAccountTargets = utils.awsAccountTargets
self.awsRegionsSelection = utils.awsRegionsSelection
@@ -62,13 +62,13 @@ def __init__(self, assessmentTarget, searchPath=None):
# GCP
elif assessmentTarget == "GCP":
searchPath = "./auditors/gcp"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# parse specific values for Assessment Target - these should match 1:1 with CloudConfig
self.gcpProjectIds = utils.gcp_project_ids
# OCI
elif assessmentTarget == "OCI":
searchPath = "./auditors/oci"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# parse specific values for Assessment Target - these should match 1:1 with CloudConfig
self.ociTenancyId = utils.ociTenancyId
self.ociUserId = utils.ociUserId
@@ -78,15 +78,15 @@ def __init__(self, assessmentTarget, searchPath=None):
# Azure
elif assessmentTarget == "Azure":
searchPath = "./auditors/azure"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# Alibaba
elif assessmentTarget == "Alibaba":
searchPath = "./auditors/alibabacloud"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# VMWare Cloud on AWS
elif assessmentTarget == "VMC":
searchPath = "./auditors/vmwarecloud"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
###################################
# SOFTWARE-AS-A-SERVICE PROVIDERS #
@@ -94,11 +94,11 @@ def __init__(self, assessmentTarget, searchPath=None):
# Servicenow
elif assessmentTarget == "Servicenow":
searchPath = "./auditors/servicenow"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# M365
elif assessmentTarget == "M365":
searchPath = "./auditors/m365"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# parse specific values for Assessment Target - these should match 1:1 with CloudConfig
self.m365TenantLocation = utils.m365TenantLocation
self.m365ClientId = utils.m365ClientId
@@ -107,7 +107,7 @@ def __init__(self, assessmentTarget, searchPath=None):
# Salesforce
elif assessmentTarget == "Salesforce":
searchPath = "./auditors/salesforce"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
self.salesforceAppClientId = utils.salesforceAppClientId
self.salesforceAppClientSecret = utils.salesforceAppClientSecret
self.salesforceApiUsername = utils.salesforceApiUsername
@@ -117,15 +117,15 @@ def __init__(self, assessmentTarget, searchPath=None):
# GitHub
elif assessmentTarget == "GitHub":
searchPath = "./auditors/github"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# Google Workspaces
elif assessmentTarget == "GoogleWorkspaces":
searchPath = "./auditors/google_workspaces"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# Workday ERP
elif assessmentTarget == "Workday":
searchPath = "./auditors/workday_erp"
- utils = CloudConfig(assessmentTarget)
+ utils = CloudConfig(assessmentTarget, tomlPath)
# Search path for Auditors
self.source = self.plugin_base.make_plugin_source(
From 530b4038b2145b939160d42854fdeba00afb20ea Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sat, 3 Feb 2024 23:04:52 -0500
Subject: [PATCH 02/10] output docs update for KDF
---
docs/outputs/OUTPUTS.md | 41 ++++++++++++++++++++++++++---------------
docs/setup/Setup_AWS.md | 2 +-
2 files changed, 27 insertions(+), 16 deletions(-)
diff --git a/docs/outputs/OUTPUTS.md b/docs/outputs/OUTPUTS.md
index 5a84102a..7edf43a4 100644
--- a/docs/outputs/OUTPUTS.md
+++ b/docs/outputs/OUTPUTS.md
@@ -11,6 +11,7 @@ This documentation is all about Outputs supported by ElectricEye and how to conf
- [HTML Compliance Output](#html-compliance-output)
- [Normalized JSON Output](#json-normalized-output)
- [Cloud Asset Management JSON Output](#json-cloud-asset-management-cam-output)
+- [Open Cyber Security Format (OCSF) V1.1.0 Output](#open-cyber-security-format-ocsf-v110-output)
- [CSV Output](#csv-output)
- [AWS Security Hub Output](#aws-security-hub-output)
- [MongoDB & AWS DocumentDB Output](#mongodb--aws-documentdb-output)
@@ -18,10 +19,10 @@ This documentation is all about Outputs supported by ElectricEye and how to conf
- [PostgreSQL Output](#postgresql-output)
- [Cloud Asset Management PostgreSQL Output](#postgresql-cloud-asset-management-cam-output)
- [Firemon Cloud Defense (DisruptOps) Output](#firemon-cloud-defense-disruptops-output)
-- [AWS DynamoDB Output](#aws-dynamodb-output)
- [Amazon Simple Queue Service (SQS) Output](#amazon-simple-queue-service-sqs-output)
- [Slack Output](#slack-output)
-- [Microsoft Teams Summary Output](#microsoft-teams-summary-output)
+- [AWS Security Finding Format (ASFF) -> Amazon Kinesis Data Firehose](#aws-security-finding-format-asff---amazon-kinesis-data-firehose)
+- [Open Cybersecurity Format (OCSF) -> Amazon Kinesis Data Firehose](#open-cybersecurity-format-ocsf---amazon-kinesis-data-firehose)
## Key Considerations
@@ -386,6 +387,8 @@ arn:aws-iso:ec2:us-iso-west-1:111111111111:volume/vol-123456abcdef/ebs-volume-en
## AWS Security Hub Output
+**IMPORTANT NOTE**: This requires `securityhub:BatchImportFindings` IAM permissions!
+
The AWS Security Hub Output selection will write all ElectricEye findings into AWS Security Hub using the BatchImportFindings API in chunks of 100. All ElectricEye findings are already in ASFF, so no other processing is done to them, besides removing `ProductFields.AssetDetails` as Security Hub *cannot* support dicts or other complex types within `ProductFields`.
This Output will *not* provide the `ProductFields.AssetDetails` information.
@@ -1111,16 +1114,10 @@ Additionally, values within the `[outputs.postgresql]` section of the TOML file
- **`firemon_cloud_defense_api_key_value`**: This variable should be set to the API Key for your FireMon Cloud Defense tenant. This key is used to authenticate with the FireMon Cloud Defense API. The location where these credentials are stored should match the value of the `global.credentials_location` variable, which specifies the location of the credentials for all integrations.
-### Example Firemon Cloud Defense (DisruptOps) Output
-
-**NOT AVAILABLE**
-
-## AWS DynamoDB Output
-
-*Coming Soon*
-
## Amazon Simple Queue Service (SQS) Output
+**IMPORTANT NOTE**: This requires `sqs:SendMessage` IAM permissions!
+
The Amazon SQS Output selection will write all ElectricEye findings to an Amazon Simple Queue Service (SQS) queue by using `json.dumps()` to insert messages into the queue with a one-second delay. To make use of the messages in the queue, ensure you are parsing the `["body"]` using `json.loads()`, or using another library in your preferred language to load the stringified JSON back into a proper JSON object. Using Amazon SQS is a great way to distribute ElectricEye findings to many other locations using various messaging service architectures with Lambda or Amazon Simple Notification Service (SNS) topics.
This Output will provide the `ProductFields.AssetDetails` information.
@@ -1218,14 +1215,28 @@ An example of the "Findings" output.
-## Microsoft Teams Summary Output
+## AWS Security Finding Format (ASFF) -> Amazon Kinesis Data Firehose
+
+**IMPORTANT NOTE**: This requires `firehose:PutRecordBatch` IAM permissions!
-*Coming Soon*
+This output will send the default AWS Security Finding Format (ASFF) records to Kinesis Data Firehose. Kinesis Data Firehouse is an extremely high-throughput data streaming service on AWS that allows you to batch several 100 events per second to select locations such as Snowflake, Splunk, Amazon S3, Datadog, OpenSearch Service, and more. You can configure buffering which allows your records to be batch-written to locations, this is helpful for building data lakes on AWS as you can ensure you have as big as a file as you can to keep the overall amount of files low. Additionally, you can configure dynamic partitioning in certain platforms to craft Hive-like partitions (e.g., `year=YYYY/month=MM/day=DD` and so on), additionally for certain locations you can automatically transform the data into the Apache Parquet columnar binary format or use AWS Lambda to perform Extraction-Loading-Transformation (ELT) to the records.
-## Open Security Finding Format (OCSF) v1.1.0
+This Output will *not* provide the `ProductFields.AssetDetails` information.
+
+To use this Output include the following arguments in your ElectricEye CLI: `python3 eeauditor/controller.py {..args..} -o asff_kdf`
+
+Additionally, values within the `[outputs.firehose]` section of the TOML file *must be provided* for this integration to work.
+
+## Open Cybersecurity Format (OCSF) -> Amazon Kinesis Data Firehose
-The Open Security Finding Format (OCSF) v1.1.0 Output will write all ElectricEye findings to a JSON file using Python's `json.dumps()` in the OCSF v1.1.0 format (as of 21 NOV 2023 `v1.1.0-dev` is still the tag). OCSF is a normalized security data format, ElectricEye makes use of the proposed [Compliance Finding (2003)](https://schema.ocsf.io/1.1.0-dev/classes/compliance_finding?extensions=) Event Class to normalize data about the finding, related compliance controls, remediation, resource and cloud-specific information.
+**IMPORTANT NOTE**: This requires `firehose:PutRecordBatch` IAM permissions!
+
+This output will send whichever the most up-to-date version of OCSF that ElectricEye supports to Kinesis Data Firehose, as of 4 FEB 2024 that is OCSF V1.1.0 mapped into Compliance Findings. Kinesis Data Firehouse is an extremely high-throughput data streaming service on AWS that allows you to batch several 100 events per second to select locations such as Snowflake, Splunk, Amazon S3, Datadog, OpenSearch Service, and more. You can configure buffering which allows your records to be batch-written to locations, this is helpful for building data lakes on AWS as you can ensure you have as big as a file as you can to keep the overall amount of files low. Additionally, you can configure dynamic partitioning in certain platforms to craft Hive-like partitions (e.g., `year=YYYY/month=MM/day=DD` and so on), additionally for certain locations you can automatically transform the data into the Apache Parquet columnar binary format or use AWS Lambda to perform Extraction-Loading-Transformation (ELT) to the records.
+
+As an added bonus, this is well suited for adding a custom CSPM, EASM & SSPM source into your Amazon Security Lake or Snowflake Data Cloud!
This Output will provide the `ProductFields.AssetDetails` information.
-To use this Output include the following arguments in your ElectricEye CLI: `python3 eeauditor/controller.py {..args..} -o ocsf_v1_1_0 --output-file my_file_name_here`
\ No newline at end of file
+To use this Output include the following arguments in your ElectricEye CLI: `python3 eeauditor/controller.py {..args..} -o ocsf_kdf`
+
+Additionally, values within the `[outputs.firehose]` section of the TOML file *must be provided* for this integration to work.
\ No newline at end of file
diff --git a/docs/setup/Setup_AWS.md b/docs/setup/Setup_AWS.md
index 6f54633c..c1784ba5 100644
--- a/docs/setup/Setup_AWS.md
+++ b/docs/setup/Setup_AWS.md
@@ -25,7 +25,7 @@ All AWS API interactivity is handled by `boto3` (and to a lesser extent lower-le
| Retrieving Accounts from one or more of your AWS Organizational Units | `organizations:ListAccountsForParent` | **NO** | You must either be in your Organizations Management Account or you must be a Delegated Administrator for an Organizations-enabled Service such as AWS Firewall Manager or Amazon GuardDuty |
| Sending findings to AWS Security Hub | `securityhub:BatchImportFindings` | **NO** | Ensure that AWS Security Hub is enabled in your Account & Region |
| Sending findings to Amazon SQS | `sqs:SendMessage` | **NO** | Ensure that your SQS Queue's Resource Policy also allows your IAM principal to `sqs:SendMessage` to it. You will also require `kms:Decrypt` permissions and access to the key (via Key Policy) if you encrypt your Queue with a Customer Managed Key. |
-| Sending findings to Amazon DynamoDB | `dynamodb:PutItem` | **NO** | You will also require `kms:Decrypt` permissions and access to the key (via Key Policy) if you encrypt your Table with a Customer Managed Key |
+| Sending findings to Amazon Kinesis Data Firehose | `firehose:PutRecordBatch` | **NO** | You will also require `kms:Decrypt` permissions and access to the key (via Key Policy) if you encrypt your Records going to KDF with a Customer Managed Key |
| Retrieving credentials from AWS Systems Manager Parameter Store | `ssm:GetParameter*` | **NO** | You will also require `kms:Decrypt` permissions and access to the key (via Key Policy) if you encrypt your SecureString Parameters with a Customer Managed Key |
| Retrieving credentials from AWS Secrets Manager | `secretsmanager:GetSecretValue` | **NO** | You will also require `kms:Decrypt` permissions and access to the key (via Key Policy) if you encrypt your Secrets with a Customer Managed Key |
| If you run ElectricEye within a container without a seperate block device or file share managed, you will need to send file-based Outputs to S3, maybe | `s3:PutObject` | **NO** | If you do use S3, ensure that your Bucket Policy allows you to perform `s3:PutObject`. You will also require `kms:Decrypt` permissions and access to the key (via Key Policy) if you encrypt your Bucket with a Customer Managed Key. |
From 6090cb260f2e1fa278ad8e410958791453d5c214 Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sat, 3 Feb 2024 23:37:45 -0500
Subject: [PATCH 03/10] hacky TOML file location for outputs
---
eeauditor/controller.py | 6 +
.../processor/outputs/amazon_sqs_output.py | 17 +-
.../processor/outputs/cam_mongodb_output.py | 15 +-
.../outputs/cam_postgresql_output.py | 17 +-
.../processor/outputs/dynamodb_output.py | 105 ------
.../outputs/firemon_cloud_defense_output.py | 17 +-
eeauditor/processor/outputs/mongodb_output.py | 17 +-
.../outputs/ocsf_to_firehose_output.py | 327 ++++++++++++++++++
.../processor/outputs/ocsf_v1_1_0_output.py | 51 +--
.../processor/outputs/postgresql_output.py | 17 +-
eeauditor/processor/outputs/slack_output.py | 17 +-
11 files changed, 428 insertions(+), 178 deletions(-)
delete mode 100644 eeauditor/processor/outputs/dynamodb_output.py
create mode 100644 eeauditor/processor/outputs/ocsf_to_firehose_output.py
diff --git a/eeauditor/controller.py b/eeauditor/controller.py
index 8a543ed0..dc403846 100644
--- a/eeauditor/controller.py
+++ b/eeauditor/controller.py
@@ -23,6 +23,7 @@
from insights import create_sechub_insights
from eeauditor import EEAuditor
from processor.main import get_providers, process_findings
+from os import environ
def print_controls(assessmentTarget, auditorName=None):
app = EEAuditor(assessmentTarget)
@@ -60,6 +61,11 @@ def run_auditor(assessmentTarget, auditorName=None, pluginName=None, delay=0, ou
findings = list(app.run_non_aws_checks(pluginName=pluginName, delay=delay))
print(f"Done running Checks for {assessmentTarget}")
+
+ if tomlPath is None:
+ environ["TOML_FILE_PATH"] = "None"
+ else:
+ environ["TOML_FILE_PATH"] = tomlPath
# Multiple outputs supported
process_findings(
diff --git a/eeauditor/processor/outputs/amazon_sqs_output.py b/eeauditor/processor/outputs/amazon_sqs_output.py
index 2fc06a81..5f130f35 100644
--- a/eeauditor/processor/outputs/amazon_sqs_output.py
+++ b/eeauditor/processor/outputs/amazon_sqs_output.py
@@ -21,7 +21,7 @@
import tomli
import boto3
import sys
-from os import path
+import os
import json
from base64 import b64decode
#from hashlib import new as hasher
@@ -37,13 +37,16 @@ class JsonProvider(object):
def __init__(self):
print("Preparing Amazon SQS output.")
- # Get the absolute path of the current directory
- currentDir = path.abspath(path.dirname(__file__))
- # Go two directories back to /eeauditor/
- twoBack = path.abspath(path.join(currentDir, "../../"))
+ if os.environ["TOML_FILE_PATH"] == "None":
+ # Get the absolute path of the current directory
+ currentDir = os.path.abspath(os.path.dirname(__file__))
+ # Go two directories back to /eeauditor/
+ twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
+ # TOML is located in /eeauditor/ directory
+ tomlFile = f"{twoBack}/external_providers.toml"
+ else:
+ tomlFile = os.environ["TOML_FILE_PATH"]
- # TOML is located in /eeauditor/ directory
- tomlFile = f"{twoBack}/external_providers.toml"
with open(tomlFile, "rb") as f:
data = tomli.load(f)
diff --git a/eeauditor/processor/outputs/cam_mongodb_output.py b/eeauditor/processor/outputs/cam_mongodb_output.py
index c2cdb86e..dbaf839c 100644
--- a/eeauditor/processor/outputs/cam_mongodb_output.py
+++ b/eeauditor/processor/outputs/cam_mongodb_output.py
@@ -43,13 +43,16 @@ class CamMongodbProvider(object):
def __init__(self):
print("Preparing MongoDB / AWS DocumentDB credentials and PEM files (as needed).")
- # Get the absolute path of the current directory
- currentDir = os.path.abspath(os.path.dirname(__file__))
- # Go two directories back to /eeauditor/
- twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
+ if os.environ["TOML_FILE_PATH"] == "None":
+ # Get the absolute path of the current directory
+ currentDir = os.path.abspath(os.path.dirname(__file__))
+ # Go two directories back to /eeauditor/
+ twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
+ # TOML is located in /eeauditor/ directory
+ tomlFile = f"{twoBack}/external_providers.toml"
+ else:
+ tomlFile = os.environ["TOML_FILE_PATH"]
- # TOML is located in /eeauditor/ directory
- tomlFile = f"{twoBack}/external_providers.toml"
with open(tomlFile, "rb") as f:
data = tomli.load(f)
diff --git a/eeauditor/processor/outputs/cam_postgresql_output.py b/eeauditor/processor/outputs/cam_postgresql_output.py
index 65dffd9a..6e6f8c01 100644
--- a/eeauditor/processor/outputs/cam_postgresql_output.py
+++ b/eeauditor/processor/outputs/cam_postgresql_output.py
@@ -42,13 +42,16 @@ class CamPostgresProvider(object):
def __init__(self):
print("Preparing PostgreSQL credentials.")
- # Get the absolute path of the current directory
- currentDir = os.path.abspath(os.path.dirname(__file__))
- # Go two directories back to /eeauditor/
- twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
-
- # TOML is located in /eeauditor/ directory
- tomlFile = f"{twoBack}/external_providers.toml"
+ if os.environ["TOML_FILE_PATH"] == "None":
+ # Get the absolute path of the current directory
+ currentDir = os.path.abspath(os.path.dirname(__file__))
+ # Go two directories back to /eeauditor/
+ twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
+ # TOML is located in /eeauditor/ directory
+ tomlFile = f"{twoBack}/external_providers.toml"
+ else:
+ tomlFile = os.environ["TOML_FILE_PATH"]
+
with open(tomlFile, "rb") as f:
data = tomli.load(f)
diff --git a/eeauditor/processor/outputs/dynamodb_output.py b/eeauditor/processor/outputs/dynamodb_output.py
deleted file mode 100644
index 143cdaf4..00000000
--- a/eeauditor/processor/outputs/dynamodb_output.py
+++ /dev/null
@@ -1,105 +0,0 @@
-#This file is part of ElectricEye.
-#SPDX-License-Identifier: Apache-2.0
-
-#Licensed to the Apache Software Foundation (ASF) under one
-#or more contributor license agreements. See the NOTICE file
-#distributed with this work for additional information
-#regarding copyright ownership. The ASF licenses this file
-#to you under the Apache License, Version 2.0 (the
-#"License"); you may not use this file except in compliance
-#with the License. You may obtain a copy of the License at
-
-#http://www.apache.org/licenses/LICENSE-2.0
-
-#Unless required by applicable law or agreed to in writing,
-#software distributed under the License is distributed on an
-#"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-#KIND, either express or implied. See the License for the
-#specific language governing permissions and limitations
-#under the License.
-import boto3
-import sys
-import os
-from processor.outputs.output_base import ElectricEyeOutput
-
-# export DYNAMODB_TABLE_NAME='EEBackend'
-
-@ElectricEyeOutput
-class JsonProvider(object):
- __provider__ = "ddb_backend"
-
- def __init__(self):
- # DynamoDB Table Name
- try:
- ddbBackendTableName = os.environ["DYNAMODB_TABLE_NAME"]
- except KeyError:
- ddbBackendTableName = "placeholder"
-
- if ddbBackendTableName == ("placeholder" or None):
- print('Valid DynamoDB Table name was not provided!')
- sys.exit(2)
- else:
- self.db_name = ddbBackendTableName
-
- def write_findings(self, findings: list, **kwargs):
-
- print(f"Writing {len(findings)} findings to backend")
-
- dynamodb = boto3.resource("dynamodb")
- table = dynamodb.Table(self.db_name)
-
- # loop the findings and create a flatter structure - better for indexing without the nested lists
- for fi in findings:
- # Pull out the Finding ID just in case there is an underlying `KeyError` issue for debug
- findingId = fi["Id"]
- # some values may not always be present (Details, etc.) - change this to an empty Map
- try:
- resourceDetails = fi["Resources"][0]["Details"]
- if not resourceDetails:
- resourceDetails = []
- except KeyError:
- resourceDetails = []
- # Partition data mapping
- partition = fi["Resources"][0]["Partition"]
- if partition == "aws":
- partitionName = "AWS Commercial"
- elif partition == "aws-us-gov":
- partitionName = "AWS GovCloud"
- elif partition == "aws-cn":
- partitionName = "AWS China"
- elif partition == "aws-isob":
- partitionName = "AWS ISOB" # Secret Region
- elif partition == "aws-iso":
- partitionName = "AWS ISO" # Top Secret Region
- # Chop up the Title to remove the finding ID
- title = str(fi["Title"]).split('] ')[1]
-
- try:
- # This format should map to FastAPI schema
- tableItem = {
- "FindingId": findingId,
- "Provider": "AWS",
- "ProviderAccountId": fi["AwsAccountId"],
- "CreatedAt": str(fi["CreatedAt"]),
- "Severity": fi["Severity"]["Label"].lower().capitalize(),
- "Title": title,
- "Description": fi["Description"],
- "RecommendationText": str(fi["Remediation"]["Recommendation"]["Text"]),
- "RecommendationUrl": str(fi["Remediation"]["Recommendation"]["Url"]),
- "ResourceType": str(fi["Resources"][0]["Type"]),
- "ResourceId": str(fi["Resources"][0]["Id"]),
- "ResourcePartition": partitionName,
- "ResourceDetails": resourceDetails,
- "FindingStatus": fi["Workflow"]["Status"].lower().capitalize(),
- "AuditReadinessMapping": fi["Compliance"]["RelatedRequirements"],
- "AuditReadinessStatus": fi["Compliance"]["Status"].lower().capitalize()
- }
- # Write to DDB
- table.put_item(
- Item=tableItem
- )
- except KeyError as e:
- print(f"Issue with Finding ID {findingId} due to missing value {e}")
- continue
-
- return True
\ No newline at end of file
diff --git a/eeauditor/processor/outputs/firemon_cloud_defense_output.py b/eeauditor/processor/outputs/firemon_cloud_defense_output.py
index 2125ffea..4b0bf5c9 100644
--- a/eeauditor/processor/outputs/firemon_cloud_defense_output.py
+++ b/eeauditor/processor/outputs/firemon_cloud_defense_output.py
@@ -42,13 +42,16 @@ class FiremonCloudDefenseProvider(object):
def __init__(self):
print("Preparing Firemon Cloud Defense (DisruptOps) credentials.")
- # Get the absolute path of the current directory
- currentDir = os.path.abspath(os.path.dirname(__file__))
- # Go two directories back to /eeauditor/
- twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
-
- # TOML is located in /eeauditor/ directory
- tomlFile = f"{twoBack}/external_providers.toml"
+ if os.environ["TOML_FILE_PATH"] == "None":
+ # Get the absolute path of the current directory
+ currentDir = os.path.abspath(os.path.dirname(__file__))
+ # Go two directories back to /eeauditor/
+ twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
+ # TOML is located in /eeauditor/ directory
+ tomlFile = f"{twoBack}/external_providers.toml"
+ else:
+ tomlFile = os.environ["TOML_FILE_PATH"]
+
with open(tomlFile, "rb") as f:
data = tomli.load(f)
diff --git a/eeauditor/processor/outputs/mongodb_output.py b/eeauditor/processor/outputs/mongodb_output.py
index 1e7c2ac5..02aba523 100644
--- a/eeauditor/processor/outputs/mongodb_output.py
+++ b/eeauditor/processor/outputs/mongodb_output.py
@@ -48,13 +48,16 @@ class MongodbProvider(object):
def __init__(self):
print("Preparing MongoDB / AWS DocumentDB credentials and PEM files (as needed).")
- # Get the absolute path of the current directory
- currentDir = os.path.abspath(os.path.dirname(__file__))
- # Go two directories back to /eeauditor/
- twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
-
- # TOML is located in /eeauditor/ directory
- tomlFile = f"{twoBack}/external_providers.toml"
+ if os.environ["TOML_FILE_PATH"] == "None":
+ # Get the absolute path of the current directory
+ currentDir = os.path.abspath(os.path.dirname(__file__))
+ # Go two directories back to /eeauditor/
+ twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
+ # TOML is located in /eeauditor/ directory
+ tomlFile = f"{twoBack}/external_providers.toml"
+ else:
+ tomlFile = os.environ["TOML_FILE_PATH"]
+
with open(tomlFile, "rb") as f:
data = tomli.load(f)
diff --git a/eeauditor/processor/outputs/ocsf_to_firehose_output.py b/eeauditor/processor/outputs/ocsf_to_firehose_output.py
new file mode 100644
index 00000000..a4b3726a
--- /dev/null
+++ b/eeauditor/processor/outputs/ocsf_to_firehose_output.py
@@ -0,0 +1,327 @@
+#This file is part of ElectricEye.
+#SPDX-License-Identifier: Apache-2.0
+
+#Licensed to the Apache Software Foundation (ASF) under one
+#or more contributor license agreements. See the NOTICE file
+#distributed with this work for additional information
+#regarding copyright ownership. The ASF licenses this file
+#to you under the Apache License, Version 2.0 (the
+#"License"); you may not use this file except in compliance
+#with the License. You may obtain a copy of the License at
+
+#http://www.apache.org/licenses/LICENSE-2.0
+
+#Unless required by applicable law or agreed to in writing,
+#software distributed under the License is distributed on an
+#"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#KIND, either express or implied. See the License for the
+#specific language governing permissions and limitations
+#under the License.
+
+import logging
+import sys
+from typing import NamedTuple
+from os import path
+from processor.outputs.output_base import ElectricEyeOutput
+import json
+from base64 import b64decode
+from datetime import datetime
+
+logger = logging.getLogger("OCSF_to_KDF_Output")
+
+# NOTE TO SELF: Updated this and FAQ.md as new standards are added
+SUPPORTED_FRAMEWORKS = [
+ "NIST CSF V1.1",
+ "NIST SP 800-53 Rev. 4",
+ "AICPA TSC",
+ "ISO 27001:2013",
+ "CIS Critical Security Controls V8",
+ "NIST SP 800-53 Rev. 5",
+ "NIST SP 800-171 Rev. 2",
+ "CSA Cloud Controls Matrix V4.0",
+ "CMMC 2.0",
+ "UK NCSC Cyber Essentials V2.2",
+ "HIPAA Security Rule 45 CFR Part 164 Subpart C",
+ "FFIEC Cybersecurity Assessment Tool",
+ "NERC Critical Infrastructure Protection",
+ "NYDFS 23 NYCRR Part 500",
+ "UK NCSC Cyber Assessment Framework V3.1",
+ "PCI-DSS V4.0",
+ "NZISM V3.5",
+ "ISO 27001:2022",
+ "Critical Risk Profile V1.2",
+ "ECB CROE",
+ "Equifax SCF V1.0",
+ "FBI CJIS Security Policy V5.9",
+ "CIS Amazon Web Services Foundations Benchmark V1.5"
+]
+
+class AsffOcsfNormalizedMapping(NamedTuple):
+ severityId: int
+ severity: str
+ cloudAccountTypeId: int
+ cloudAccountType: str
+ complianceStatusId: int
+ complianceStatus: str
+
+here = path.abspath(path.dirname(__file__))
+with open(f"{here}/mapped_compliance_controls.json") as jsonfile:
+ CONTROLS_CROSSWALK = json.load(jsonfile)
+
+@ElectricEyeOutput
+class OcsfFirehoseOutput(object):
+ __provider__ = "ocsf_kdf"
+
+ def write_findings(self, findings: list, output_file: str, **kwargs):
+ if len(findings) == 0:
+ logger.error("There are not any findings to send to Kinesis Data Firehose!")
+ sys.exit(0)
+
+ logger.info(
+ "Writing %s OCSF Compliance Findings to Kinesis Data Firehose!",
+ len(findings)
+ )
+
+ """# Use another list comprehension to remove `ProductFields.AssetDetails` from non-Asset reporting outputs
+ newFindings = [
+ {**d, "ProductFields": {k: v for k, v in d["ProductFields"].items() if k != "AssetDetails"}} for d in findings
+ ]
+
+ del findings"""
+
+ """
+ This list comprhension will base64 decode and convert a string to JSON for all instances of `ProductFields.AssetDetails`
+ except where it is a None type (this is done for placeholders in Checks where the Asset doesn't exist) and it will also
+ skip over areas in the event that `ProductFields` is missing any Cloud Asset Management required fields
+ """
+ decodedFindings = [
+ {**d, "ProductFields": {**d["ProductFields"],
+ "AssetDetails": json.loads(b64decode(d["ProductFields"]["AssetDetails"]).decode("utf-8"))
+ if d["ProductFields"]["AssetDetails"] is not None
+ else None
+ }} if "AssetDetails" in d["ProductFields"]
+ else d
+ for d in findings
+ ]
+
+ del findings
+
+ # Map in the new compliance controls
+ for finding in decodedFindings:
+ complianceRelatedRequirements = list(finding["Compliance"]["RelatedRequirements"])
+ newControls = []
+ nistCsfControls = [control for control in complianceRelatedRequirements if control.startswith("NIST CSF V1.1")]
+ for control in nistCsfControls:
+ crosswalkedControls = self.nist_csf_v_1_1_controls_crosswalk(control)
+ # Not every single NIST CSF Control maps across to other frameworks
+ if crosswalkedControls:
+ for crosswalk in crosswalkedControls:
+ if crosswalk not in newControls:
+ newControls.append(crosswalk)
+ else:
+ continue
+
+ complianceRelatedRequirements.extend(newControls)
+
+ del finding["Compliance"]["RelatedRequirements"]
+ finding["Compliance"]["RelatedRequirements"] = complianceRelatedRequirements
+
+ ocsfFindings = self.ocsf_compliance_finding_mapping(decodedFindings)
+
+ del decodedFindings
+
+ return True
+
+ def nist_csf_v_1_1_controls_crosswalk(self, nistCsfSubcategory):
+ """
+ This function returns a list of additional control framework control IDs that mapped into a provided
+ NIST CSF V1.1 Subcategory (control)
+ """
+
+ # Not every single NIST CSF Control maps across to other frameworks
+ try:
+ return CONTROLS_CROSSWALK[nistCsfSubcategory]
+ except KeyError:
+ return []
+
+ def asff_to_ocsf_normalization(self, severityLabel: str, cloudProvider: str, complianceStatusLabel: str) -> AsffOcsfNormalizedMapping:
+ """
+ Normalizes the following ASFF Severity, Cloud Account Provider, and Compliance values into OCSF
+ """
+
+ # map Severity.Label -> base_event.severity_id, base_event.severity
+ if severityLabel == "INFORMATIONAL":
+ severityId = 1
+ severity = severityLabel.lower().capitalize()
+ if severityLabel == "LOW":
+ severityId = 2
+ severity = severityLabel.lower().capitalize()
+ if severityLabel == "MEDIUM":
+ severityId = 3
+ severity = severityLabel.lower().capitalize()
+ if severityLabel == "HIGH":
+ severityId = 4
+ severity = severityLabel.lower().capitalize()
+ if severityLabel == "CRITICAL":
+ severityId = 5
+ severity = severityLabel.lower().capitalize()
+ else:
+ severityId = 99
+ severity = severityLabel.lower().capitalize()
+
+ # map ProductFields.Provider -> cloud.account.type_id, cloud.account.type
+ if cloudProvider == "AWS":
+ acctTypeId = 10
+ acctType = "AWS Account"
+ elif cloudProvider == "GCP":
+ acctTypeId = 5
+ acctType = "GCP Account"
+ else:
+ acctTypeId = 99
+ acctType = cloudProvider
+
+ # map Compliance.Status -> compliance.status_id, compliance.status
+ if complianceStatusLabel == "PASSED":
+ complianceStatusId = 1
+ complianceStatus = "Pass"
+ elif complianceStatusLabel == "WARNING":
+ complianceStatusId = 2
+ complianceStatus = "Warning"
+ elif complianceStatusLabel == "FAILED":
+ complianceStatusId = 3
+ complianceStatus = "Fail"
+ else:
+ complianceStatusId = 99
+ complianceStatus = complianceStatusLabel.lower().capitalize()
+
+ return (
+ severityId,
+ severity,
+ acctTypeId,
+ acctType,
+ complianceStatusId,
+ complianceStatus
+ )
+
+ def iso8061_to_epochseconds(self, iso8061: str) -> int:
+ """
+ Converts ISO 8061 datetime into Epochseconds timestamp
+ """
+ return int(datetime.fromisoformat(iso8061).timestamp())
+
+ def ocsf_compliance_finding_mapping(self, findings: list) -> list:
+ """
+ Takes ElectricEye ASFF and outputs to OCSF v1.1.0 Compliance Finding (2003), returns a list of new findings
+ """
+
+ ocsfFindings = []
+
+ logger.info("Mapping ASFF to OCSF")
+
+ for finding in findings:
+
+ asffToOcsf = self.asff_to_ocsf_normalization(
+ severityLabel=finding["Severity"]["Label"],
+ cloudProvider=finding["ProductFields"]["Provider"],
+ complianceStatusLabel=finding["Compliance"]["Status"]
+ )
+
+ ocsf = {
+ # Base Event data
+ "activity_id": 1,
+ "activity_name": "Create",
+ "category_name": "Findings",
+ "category_uid": 2,
+ "class_name": "Compliance Finding",
+ "class_uid": 2003,
+ "confidence_score": finding["Confidence"],
+ "severity": asffToOcsf[1],
+ "severity_id": asffToOcsf[0],
+ "status": "New",
+ "status_id": 1,
+ "time": self.iso8061_to_epochseconds(finding["CreatedAt"]),
+ "type_name": "Compliance Finding: Create",
+ "type_uid": 200301,
+ # Profiles / Metadata
+ "metadata": {
+ "uid": finding["Id"],
+ "correlation_uid": finding["GeneratorId"],
+ "version":"1.1.0",
+ "product": {
+ "name":"ElectricEye",
+ "version":"3.0",
+ "url_string":"https://github.com/jonrau1/ElectricEye",
+ "vendor_name":"ElectricEye"
+ },
+ "profiles":[
+ "cloud"
+ ]
+ },
+ "cloud": {
+ "provider": finding["ProductFields"]["Provider"],
+ "project_uid": finding["ProductFields"]["ProviderAccountId"],
+ "region": finding["ProductFields"]["AssetRegion"],
+ "account": {
+ "uid": finding["ProductFields"]["ProviderAccountId"],
+ "type": asffToOcsf[3],
+ "type_uid": asffToOcsf[2]
+ }
+ },
+ # Observables
+ "observables": [
+ # Cloud Account (Project) UID
+ {
+ "name": "cloud.project_uid",
+ "type": "Resource UID",
+ "type_id": 10,
+ "value": finding["ProductFields"]["ProviderAccountId"]
+ },
+ # Resource UID
+ {
+ "name": "resource.uid",
+ "type": "Resource UID",
+ "type_id": 10,
+ "value": finding["Resources"][0]["Id"]
+ }
+ ],
+ # Compliance Finding Class Info
+ "compliance": {
+ "requirements": finding["Compliance"]["RelatedRequirements"],
+ "control": str(finding["Title"]).split("] ")[0].replace("[",""),
+ "standards": SUPPORTED_FRAMEWORKS,
+ "status": asffToOcsf[5],
+ "status_id": asffToOcsf[4]
+ },
+ "finding_info": {
+ "created_time": self.iso8061_to_epochseconds(finding["CreatedAt"]),
+ "desc": finding["Description"],
+ "first_seen_time": self.iso8061_to_epochseconds(finding["FirstObservedAt"]),
+ "modified_time": self.iso8061_to_epochseconds(finding["UpdatedAt"]),
+ "product_uid": finding["ProductArn"],
+ "title": finding["Title"],
+ "types": finding["Types"],
+ "uid": finding["Id"]
+ },
+ "remediation": {
+ "desc": finding["Remediation"]["Recommendation"]["Text"],
+ "references": [finding["Remediation"]["Recommendation"]["Url"]]
+ },
+ "resource": {
+ "data": finding["ProductFields"]["AssetDetails"],
+ "cloud_partition": finding["Resources"][0]["Partition"],
+ "region": finding["ProductFields"]["AssetRegion"],
+ "type": finding["ProductFields"]["AssetService"],
+ "uid": finding["Resources"][0]["Id"]
+ },
+ "unmapped": {
+ "provide_type": finding["ProductFields"]["ProviderType"],
+ "asset_class": finding["ProductFields"]["AssetClass"],
+ "asset_service": finding["ProductFields"]["AssetService"],
+ "asset_component": finding["ProductFields"]["AssetComponent"],
+ "workflow_status": finding["Workflow"]["Status"],
+ "record_state": finding["RecordState"]
+ }
+ }
+ ocsfFindings.append(ocsf)
+
+ return ocsfFindings
\ No newline at end of file
diff --git a/eeauditor/processor/outputs/ocsf_v1_1_0_output.py b/eeauditor/processor/outputs/ocsf_v1_1_0_output.py
index b3955089..bfad01e5 100644
--- a/eeauditor/processor/outputs/ocsf_v1_1_0_output.py
+++ b/eeauditor/processor/outputs/ocsf_v1_1_0_output.py
@@ -27,32 +27,33 @@
from base64 import b64decode
from datetime import datetime
-logger = logging.getLogger(__name__)
+logger = logging.getLogger("OCSF_V1.1.0_Output")
# NOTE TO SELF: Updated this and FAQ.md as new standards are added
-SUPPORTED_STANDARDS = [
- "NIST Cybersecurity Framework Version 1.1",
- "NIST Special Publication 800-53 Revision 4",
- "NIST Special Publication 800-53 Revision 5",
- "NIST Special Publication 800-171 Revision 2",
- "American Institute of Certified Public Accountants (AICPA) Trust Service Criteria (TSC) 2017/2020 for SOC 2",
- "ISO/IEC 27001:2013/2017 Annex A",
- "ISO/IEC 27001:2022 Annex A",
- "Center for Internet Security (CIS) Critical Security Controls Version 8",
- "Cloud Security Alliance (CSA) Cloud Controls Matrix (CCM) Version 4.0",
- "United States Department of Defense Cybersecurity Maturity Model Certification (CMMC) Version 2.0",
- "United States Federal Bureau of Investigation (FBI) Criminal Justice Information System (CJIS) Security Policy Version 5.9",
- "United Kingdom National Cybercrime Security Center (NCSC) Cyber Essentials Version 2.2",
- "United Kingdom National Cybercrime Security Center (NCSC) Assessment Framework Version 3.1",
- "HIPAA 'Security Rule' U.S. Code 45 CFR Part 164 Subpart C",
- "Federal Financial Institutions Examination Council (FFIEC) Cybersecurity Assessment Tool (CAT)",
- "North American Electric Reliability Corporation (NERC) Critical Infrastructure Protection (CIP) Standard",
- "New Zealand Information Security Manual Version 3.5",
- "New York Department of Financial Services (NYDFS) Series 23 NYCRR Part 500; AKA NYDFS500",
- "Critical Risk Institute (CRI) Critical Risk Profile Version 1.2",
- "European Central Bank (ECB) Cyber Resilience Oversight Expectations (CROEs)",
- "Equifax Security Controls Framework Version 1.0",
- "Payment Card Industry (PCI) Data Security Standard (DSS) Version 4.0"
+SUPPORTED_FRAMEWORKS = [
+ "NIST CSF V1.1",
+ "NIST SP 800-53 Rev. 4",
+ "AICPA TSC",
+ "ISO 27001:2013",
+ "CIS Critical Security Controls V8",
+ "NIST SP 800-53 Rev. 5",
+ "NIST SP 800-171 Rev. 2",
+ "CSA Cloud Controls Matrix V4.0",
+ "CMMC 2.0",
+ "UK NCSC Cyber Essentials V2.2",
+ "HIPAA Security Rule 45 CFR Part 164 Subpart C",
+ "FFIEC Cybersecurity Assessment Tool",
+ "NERC Critical Infrastructure Protection",
+ "NYDFS 23 NYCRR Part 500",
+ "UK NCSC Cyber Assessment Framework V3.1",
+ "PCI-DSS V4.0",
+ "NZISM V3.5",
+ "ISO 27001:2022",
+ "Critical Risk Profile V1.2",
+ "ECB CROE",
+ "Equifax SCF V1.0",
+ "FBI CJIS Security Policy V5.9",
+ "CIS Amazon Web Services Foundations Benchmark V1.5"
]
class AsffOcsfNormalizedMapping(NamedTuple):
@@ -299,7 +300,7 @@ def ocsf_compliance_finding_mapping(self, findings: list) -> list:
"compliance": {
"requirements": finding["Compliance"]["RelatedRequirements"],
"control": str(finding["Title"]).split("] ")[0].replace("[",""),
- "standards": SUPPORTED_STANDARDS,
+ "standards": SUPPORTED_FRAMEWORKS,
"status": asffToOcsf[5],
"status_id": asffToOcsf[4]
},
diff --git a/eeauditor/processor/outputs/postgresql_output.py b/eeauditor/processor/outputs/postgresql_output.py
index 4759406b..cef430bc 100644
--- a/eeauditor/processor/outputs/postgresql_output.py
+++ b/eeauditor/processor/outputs/postgresql_output.py
@@ -46,13 +46,16 @@ class PostgresProvider(object):
def __init__(self):
print("Preparing PostgreSQL credentials.")
- # Get the absolute path of the current directory
- currentDir = os.path.abspath(os.path.dirname(__file__))
- # Go two directories back to /eeauditor/
- twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
-
- # TOML is located in /eeauditor/ directory
- tomlFile = f"{twoBack}/external_providers.toml"
+ if os.environ["TOML_FILE_PATH"] == "None":
+ # Get the absolute path of the current directory
+ currentDir = os.path.abspath(os.path.dirname(__file__))
+ # Go two directories back to /eeauditor/
+ twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
+ # TOML is located in /eeauditor/ directory
+ tomlFile = f"{twoBack}/external_providers.toml"
+ else:
+ tomlFile = os.environ["TOML_FILE_PATH"]
+
with open(tomlFile, "rb") as f:
data = tomli.load(f)
diff --git a/eeauditor/processor/outputs/slack_output.py b/eeauditor/processor/outputs/slack_output.py
index afd7911f..204336b6 100644
--- a/eeauditor/processor/outputs/slack_output.py
+++ b/eeauditor/processor/outputs/slack_output.py
@@ -48,13 +48,16 @@ class SlackProvider(object):
def __init__(self):
print("Preparing Slack credentials.")
- # Get the absolute path of the current directory
- currentDir = os.path.abspath(os.path.dirname(__file__))
- # Go two directories back to /eeauditor/
- twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
-
- # TOML is located in /eeauditor/ directory
- tomlFile = f"{twoBack}/external_providers.toml"
+ if os.environ["TOML_FILE_PATH"] == "None":
+ # Get the absolute path of the current directory
+ currentDir = os.path.abspath(os.path.dirname(__file__))
+ # Go two directories back to /eeauditor/
+ twoBack = os.path.abspath(os.path.join(currentDir, "../../"))
+ # TOML is located in /eeauditor/ directory
+ tomlFile = f"{twoBack}/external_providers.toml"
+ else:
+ tomlFile = os.environ["TOML_FILE_PATH"]
+
with open(tomlFile, "rb") as f:
data = tomli.load(f)
From 923d9a62ea4f33a4ae934c8fd2ea115c8246f1e3 Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sat, 3 Feb 2024 23:38:23 -0500
Subject: [PATCH 04/10] Oh yeah I deleted ddb_backend
---
eeauditor/processor/outputs/ocsf_to_firehose_output.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/eeauditor/processor/outputs/ocsf_to_firehose_output.py b/eeauditor/processor/outputs/ocsf_to_firehose_output.py
index a4b3726a..a93a7f28 100644
--- a/eeauditor/processor/outputs/ocsf_to_firehose_output.py
+++ b/eeauditor/processor/outputs/ocsf_to_firehose_output.py
@@ -72,7 +72,7 @@ class AsffOcsfNormalizedMapping(NamedTuple):
class OcsfFirehoseOutput(object):
__provider__ = "ocsf_kdf"
- def write_findings(self, findings: list, output_file: str, **kwargs):
+ def write_findings(self, findings: list, **kwargs):
if len(findings) == 0:
logger.error("There are not any findings to send to Kinesis Data Firehose!")
sys.exit(0)
From 03cb7c5b0b76c3397f22fec19690649d0cb3a5b1 Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sat, 3 Feb 2024 23:46:03 -0500
Subject: [PATCH 05/10] support `iso-f` and `iso-e`
---
eeauditor/cloud_utils.py | 12 ++++++++----
eeauditor/processor/outputs/amazon_sqs_output.py | 10 ++++++----
2 files changed, 14 insertions(+), 8 deletions(-)
diff --git a/eeauditor/cloud_utils.py b/eeauditor/cloud_utils.py
index c9ebca46..7f03ec74 100644
--- a/eeauditor/cloud_utils.py
+++ b/eeauditor/cloud_utils.py
@@ -552,17 +552,21 @@ def check_aws_partition(region: str):
"""
# GovCloud partition override
- if region in ["us-gov-east-1", "us-gov-west-1"]:
+ if region in ["us-gov-east-1", "us-gov-west-1"] or "us-gov-" in region:
partition = "aws-us-gov"
# China partition override
- elif region in ["cn-north-1", "cn-northwest-1"]:
+ elif region in ["cn-north-1", "cn-northwest-1"] or "cn-" in region:
partition = "aws-cn"
# AWS Secret Region override
- elif region in ["us-isob-east-1", "us-isob-west-1"]:
+ elif region in ["us-isob-east-1", "us-isob-west-1"] or "isob-" in region:
partition = "aws-isob"
# AWS Top Secret Region override
- elif region in ["us-iso-east-1", "us-iso-west-1"]:
+ elif region in ["us-iso-east-1", "us-iso-west-1"] or "iso-" in region:
partition = "aws-iso"
+ elif "iso-e" in region or "isoe" in region:
+ partition = "aws-isoe"
+ elif "iso-f" in region or "isof" in region:
+ partition = "aws-isof"
else:
partition = "aws"
diff --git a/eeauditor/processor/outputs/amazon_sqs_output.py b/eeauditor/processor/outputs/amazon_sqs_output.py
index 5f130f35..2c4a2c54 100644
--- a/eeauditor/processor/outputs/amazon_sqs_output.py
+++ b/eeauditor/processor/outputs/amazon_sqs_output.py
@@ -28,8 +28,6 @@
from botocore.exceptions import ClientError
from processor.outputs.output_base import ElectricEyeOutput
-sqs = boto3.client("sqs")
-
@ElectricEyeOutput
class JsonProvider(object):
__provider__ = "amazon_sqs"
@@ -55,15 +53,17 @@ def __init__(self):
queueUrl = sqsDetails["amazon_sqs_queue_url"]
queueBatchSize = sqsDetails["amazon_sqs_batch_size"]
+ awsRegion = sqsDetails["amazon_sqs_queue_region"]
# Ensure that values are provided for all variable - use all() and a list comprehension to check the vars
# empty strings will trigger `if not`
- if not all(s for s in [queueUrl, queueBatchSize]):
+ if not all(s for s in [queueUrl, queueBatchSize, awsRegion]):
print("An empty value was detected in '[outputs.amazon_sqs]'. Review the TOML file and try again!")
sys.exit(2)
self.queueUrl = queueUrl
self.queueBatchSize = queueBatchSize
+ self.sqs = boto3.client("sqs", region_name=awsRegion)
def write_findings(self, findings: list, **kwargs):
if len(findings) == 0:
@@ -113,8 +113,10 @@ def create_hashed_message_id(self, findingId):
def send_message_to_sqs(self, batch):
"""
- TO DO
+ Writes batches of ASFF findings into SQS
"""
+ sqs = self.sqs
+
for entry in batch:
try:
sqs.send_message(
From 2ff649b3c2832b300ee2cf45523c5655a7dc8370 Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sat, 3 Feb 2024 23:47:50 -0500
Subject: [PATCH 06/10] few more ISO-* partition detections
---
eeauditor/cloud_utils.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/eeauditor/cloud_utils.py b/eeauditor/cloud_utils.py
index 7f03ec74..ef37b599 100644
--- a/eeauditor/cloud_utils.py
+++ b/eeauditor/cloud_utils.py
@@ -563,9 +563,11 @@ def check_aws_partition(region: str):
# AWS Top Secret Region override
elif region in ["us-iso-east-1", "us-iso-west-1"] or "iso-" in region:
partition = "aws-iso"
+ # AWS UKSOF / British MOD Region override
elif "iso-e" in region or "isoe" in region:
partition = "aws-isoe"
- elif "iso-f" in region or "isof" in region:
+ # AWS Intel Community us-isof-south-1 Region override
+ elif region in ["us-isof-south-1"] or "iso-f" in region or "isof" in region:
partition = "aws-isof"
else:
partition = "aws"
From a659050048f0869a48c0e0cb8bf67a86985e564a Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sat, 3 Feb 2024 23:53:25 -0500
Subject: [PATCH 07/10] TOML update, small SQS changes
---
eeauditor/cloud_utils.py | 1 +
eeauditor/external_providers.toml | 30 +++++++++----------
.../processor/outputs/amazon_sqs_output.py | 4 ++-
3 files changed, 19 insertions(+), 16 deletions(-)
diff --git a/eeauditor/cloud_utils.py b/eeauditor/cloud_utils.py
index ef37b599..e8cc5653 100644
--- a/eeauditor/cloud_utils.py
+++ b/eeauditor/cloud_utils.py
@@ -569,6 +569,7 @@ def check_aws_partition(region: str):
# AWS Intel Community us-isof-south-1 Region override
elif region in ["us-isof-south-1"] or "iso-f" in region or "isof" in region:
partition = "aws-isof"
+ # TODO: Add European Sovreign Cloud Partition
else:
partition = "aws"
diff --git a/eeauditor/external_providers.toml b/eeauditor/external_providers.toml
index 3310e931..14a89d44 100644
--- a/eeauditor/external_providers.toml
+++ b/eeauditor/external_providers.toml
@@ -319,29 +319,19 @@ title = "ElectricEye Configuration"
mongodb_collection_name = ""
- [outputs.dynamodb]
-
- # Table name
-
- dynamodb_table_name = ""
-
[outputs.amazon_sqs]
- # Queue Name / URL
+ # Queue Name / URL, this must be in the same account as your current credentials
amazon_sqs_queue_url = ""
- # Batch
+ # Batch Size
amazon_sqs_batch_size = 10 # This must be an integer
- [outputs.microsoft_teams]
+ # Queue Region
- # The location (or actual contents) of the Webhook for your MS Teams Channel
- # this location must match the value of `global.credentials_location` e.g., if you specify "AWS_SSM" then
- # the value for this variable should be the name of the AWS Systems Manager Parameter Store SecureString Parameter
-
- microsoft_teams_webhook_value = ""
+ amazon_sqs_queue_region = ""
[outputs.slack]
@@ -372,4 +362,14 @@ title = "ElectricEye Configuration"
# A list of ElectricEye Finding States (matching the ASFF RecordState) that you want sent to slack if your selection for
# `electric_eye_slack_message_type` is "FindingS". This defaults to ["ACTIVE"]
- electric_eye_slack_finding_state_filter = ["ACTIVE"] # VALID VALUES | "ACTIVE", "ARCHIVED"
\ No newline at end of file
+ electric_eye_slack_finding_state_filter = ["ACTIVE"] # VALID VALUES | "ACTIVE", "ARCHIVED"
+
+ [outputs.firehose]
+
+ # The name of your Kinesis Data Firehose Delivery Stream, this must be in the same account as your current credentials
+
+ kinesis_firehose_delivery_stream_name = ""
+
+ # Delivery Stream Region
+
+ kinesis_firehose_region = ""
\ No newline at end of file
diff --git a/eeauditor/processor/outputs/amazon_sqs_output.py b/eeauditor/processor/outputs/amazon_sqs_output.py
index 2c4a2c54..001846d9 100644
--- a/eeauditor/processor/outputs/amazon_sqs_output.py
+++ b/eeauditor/processor/outputs/amazon_sqs_output.py
@@ -29,7 +29,7 @@
from processor.outputs.output_base import ElectricEyeOutput
@ElectricEyeOutput
-class JsonProvider(object):
+class AmazonSqsProvider(object):
__provider__ = "amazon_sqs"
def __init__(self):
@@ -54,6 +54,8 @@ def __init__(self):
queueUrl = sqsDetails["amazon_sqs_queue_url"]
queueBatchSize = sqsDetails["amazon_sqs_batch_size"]
awsRegion = sqsDetails["amazon_sqs_queue_region"]
+ if awsRegion is None or awsRegion == "":
+ awsRegion == boto3.Session().region_name
# Ensure that values are provided for all variable - use all() and a list comprehension to check the vars
# empty strings will trigger `if not`
From 2b6040e094c939c3ea71dc3676204694aeddb63f Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sun, 4 Feb 2024 00:17:49 -0500
Subject: [PATCH 08/10] `logging` updates, KDF output one
---
.../aws/AWS_License_Manager_Auditor.py | 2 +-
.../aws/AWS_TrustedAdvisor_Auditor.py | 6 +-
eeauditor/cloud_utils.py | 6 +-
.../outputs/ocsf_to_firehose_output.py | 65 ++++++++++++++++++-
4 files changed, 73 insertions(+), 6 deletions(-)
diff --git a/eeauditor/auditors/aws/AWS_License_Manager_Auditor.py b/eeauditor/auditors/aws/AWS_License_Manager_Auditor.py
index 23d016b3..31b5f60c 100644
--- a/eeauditor/auditors/aws/AWS_License_Manager_Auditor.py
+++ b/eeauditor/auditors/aws/AWS_License_Manager_Auditor.py
@@ -42,7 +42,7 @@ def get_license_manager_configurations(cache, session):
try:
liscMgrConfigs = licensemanager.list_license_configurations()["LicenseConfigurations"]
except ClientError as e:
- logger.warn(
+ logger.warning(
"Cannot retrieve Amazon License Manager configurations, this is likely due to not using this service or you deleted the IAM Service Role. Refer to the error for more information: %s",
e.response["Error"]["Message"]
)
diff --git a/eeauditor/auditors/aws/AWS_TrustedAdvisor_Auditor.py b/eeauditor/auditors/aws/AWS_TrustedAdvisor_Auditor.py
index 2c553f16..09297374 100644
--- a/eeauditor/auditors/aws/AWS_TrustedAdvisor_Auditor.py
+++ b/eeauditor/auditors/aws/AWS_TrustedAdvisor_Auditor.py
@@ -203,7 +203,7 @@ def trusted_advisor_failing_cloudfront_ssl_cert_iam_certificate_store_check(cach
}
yield finding
except IndexError:
- logging.warn(
+ logging.warning(
"Index Error was found encountered attempted to evaluate Trusted Advisor, this is likely because you do not have the appropriate AWS Support level."
)
@@ -351,7 +351,7 @@ def trusted_advisor_failing_cloudfront_ssl_cert_on_origin_check(cache: dict, ses
}
yield finding
except IndexError:
- logging.warn(
+ logging.warning(
"Index Error was found encountered attempted to evaluate Trusted Advisor, this is likely because you do not have the appropriate AWS Support level."
)
@@ -531,7 +531,7 @@ def trusted_advisor_failing_exposed_access_keys_check(cache: dict, session, awsA
}
yield finding
except IndexError:
- logging.warn(
+ logging.warning(
"Index Error was found encountered attempted to evaluate Trusted Advisor, this is likely because you do not have the appropriate AWS Support level."
)
diff --git a/eeauditor/cloud_utils.py b/eeauditor/cloud_utils.py
index e8cc5653..c530dd76 100644
--- a/eeauditor/cloud_utils.py
+++ b/eeauditor/cloud_utils.py
@@ -111,7 +111,7 @@ def __init__(self, assessmentTarget, tomlPath):
# Process ["aws_electric_eye_iam_role_name"]
electricEyeRoleName = data["regions_and_accounts"]["aws"]["aws_electric_eye_iam_role_name"]
if electricEyeRoleName is None or electricEyeRoleName == "":
- logger.warn(
+ logger.warning(
"A value for ['aws_electric_eye_iam_role_name'] was not provided. Will attempt to use current session credentials, this will likely fail if you're attempting to assess another AWS account."
)
electricEyeRoleName = None
@@ -429,6 +429,10 @@ def get_aws_regions(self):
# majority of Regions have a "opt-in-not-required", hence the "not not opted in" list comp
regions = [region["RegionName"] for region in ec2.describe_regions()["Regions"] if region["OptInStatus"] != "not-opted-in"]
except ClientError as e:
+ logger.error(
+ "Could not retrieve AWS Regions because: %s",
+ e
+ )
raise e
return regions
diff --git a/eeauditor/processor/outputs/ocsf_to_firehose_output.py b/eeauditor/processor/outputs/ocsf_to_firehose_output.py
index a93a7f28..2d2bae1e 100644
--- a/eeauditor/processor/outputs/ocsf_to_firehose_output.py
+++ b/eeauditor/processor/outputs/ocsf_to_firehose_output.py
@@ -19,13 +19,16 @@
#under the License.
import logging
+import tomli
+import boto3
import sys
from typing import NamedTuple
-from os import path
+from os import path, environ
from processor.outputs.output_base import ElectricEyeOutput
import json
from base64 import b64decode
from datetime import datetime
+from botocore.exceptions import ClientError
logger = logging.getLogger("OCSF_to_KDF_Output")
@@ -72,6 +75,39 @@ class AsffOcsfNormalizedMapping(NamedTuple):
class OcsfFirehoseOutput(object):
__provider__ = "ocsf_kdf"
+ def __init__(self):
+ print("Preparing to send OCSF V1.1.0 Compliance Findings to Amazon Kinesis Data Firehose.")
+
+ if environ["TOML_FILE_PATH"] == "None":
+ # Get the absolute path of the current directory
+ currentDir = path.abspath(path.dirname(__file__))
+ # Go two directories back to /eeauditor/
+ twoBack = path.abspath(path.join(currentDir, "../../"))
+ # TOML is located in /eeauditor/ directory
+ tomlFile = f"{twoBack}/external_providers.toml"
+ else:
+ tomlFile = environ["TOML_FILE_PATH"]
+
+ with open(tomlFile, "rb") as f:
+ data = tomli.load(f)
+
+ # Variable for the entire [outputs.amazon_sqs] section
+ sqsDetails = data["outputs"]["firehose"]
+
+ deliveryStream = sqsDetails["kinesis_firehose_delivery_stream_name"]
+ awsRegion = sqsDetails["kinesis_firehose_region"]
+ if awsRegion is None or awsRegion == "":
+ awsRegion == boto3.Session().region_name
+
+ # Ensure that values are provided for all variable - use all() and a list comprehension to check the vars
+ # empty strings will trigger `if not`
+ if not all(s for s in [deliveryStream, awsRegion]):
+ logger.error("An empty value was detected in '[outputs.firehose]'. Review the TOML file and try again!")
+ sys.exit(2)
+
+ self.deliveryStream = deliveryStream
+ self.firehose = boto3.client("firehose", region_name=awsRegion)
+
def write_findings(self, findings: list, **kwargs):
if len(findings) == 0:
logger.error("There are not any findings to send to Kinesis Data Firehose!")
@@ -129,6 +165,33 @@ def write_findings(self, findings: list, **kwargs):
ocsfFindings = self.ocsf_compliance_finding_mapping(decodedFindings)
del decodedFindings
+
+ firehose = self.firehose
+
+ # TODO: Make this more performant, because woah dawg, this shit's stupid!
+ for i in range(0, len(ocsfFindings), 25):
+ encodedRecords = []
+ records = ocsfFindings[i : i + 25]
+ for record in records:
+ encodedRecords.append({"Data": json.dumps(record).encode("utf-8")})
+ del records
+
+ try:
+ response = firehose.put_record_batch(
+ DeliveryStreamName=self.deliveryStream,
+ Records=encodedRecords
+ )
+ if response["FailedPutCount"] > 0:
+ logger.warning(
+ "Failed to deliver %s records",
+ response["FailedPutCount"]
+ )
+ except ClientError as e:
+ logger.warning(
+ "Error with sending batch to Firehose due to: %s",
+ e.response["Error"]["Message"]
+ )
+ continue
return True
From 2ad63c67b082d52ef895f744b3c8b8a62db17c70 Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sun, 4 Feb 2024 00:31:11 -0500
Subject: [PATCH 09/10] I changed my mind, fuck ASFF to KDF
---
docs/outputs/OUTPUTS.md | 13 -------------
eeauditor/processor/outputs/amazon_sqs_output.py | 2 +-
.../processor/outputs/ocsf_to_firehose_output.py | 6 ++++--
3 files changed, 5 insertions(+), 16 deletions(-)
diff --git a/docs/outputs/OUTPUTS.md b/docs/outputs/OUTPUTS.md
index 7edf43a4..8960d72e 100644
--- a/docs/outputs/OUTPUTS.md
+++ b/docs/outputs/OUTPUTS.md
@@ -21,7 +21,6 @@ This documentation is all about Outputs supported by ElectricEye and how to conf
- [Firemon Cloud Defense (DisruptOps) Output](#firemon-cloud-defense-disruptops-output)
- [Amazon Simple Queue Service (SQS) Output](#amazon-simple-queue-service-sqs-output)
- [Slack Output](#slack-output)
-- [AWS Security Finding Format (ASFF) -> Amazon Kinesis Data Firehose](#aws-security-finding-format-asff---amazon-kinesis-data-firehose)
- [Open Cybersecurity Format (OCSF) -> Amazon Kinesis Data Firehose](#open-cybersecurity-format-ocsf---amazon-kinesis-data-firehose)
## Key Considerations
@@ -1215,18 +1214,6 @@ An example of the "Findings" output.
-## AWS Security Finding Format (ASFF) -> Amazon Kinesis Data Firehose
-
-**IMPORTANT NOTE**: This requires `firehose:PutRecordBatch` IAM permissions!
-
-This output will send the default AWS Security Finding Format (ASFF) records to Kinesis Data Firehose. Kinesis Data Firehouse is an extremely high-throughput data streaming service on AWS that allows you to batch several 100 events per second to select locations such as Snowflake, Splunk, Amazon S3, Datadog, OpenSearch Service, and more. You can configure buffering which allows your records to be batch-written to locations, this is helpful for building data lakes on AWS as you can ensure you have as big as a file as you can to keep the overall amount of files low. Additionally, you can configure dynamic partitioning in certain platforms to craft Hive-like partitions (e.g., `year=YYYY/month=MM/day=DD` and so on), additionally for certain locations you can automatically transform the data into the Apache Parquet columnar binary format or use AWS Lambda to perform Extraction-Loading-Transformation (ELT) to the records.
-
-This Output will *not* provide the `ProductFields.AssetDetails` information.
-
-To use this Output include the following arguments in your ElectricEye CLI: `python3 eeauditor/controller.py {..args..} -o asff_kdf`
-
-Additionally, values within the `[outputs.firehose]` section of the TOML file *must be provided* for this integration to work.
-
## Open Cybersecurity Format (OCSF) -> Amazon Kinesis Data Firehose
**IMPORTANT NOTE**: This requires `firehose:PutRecordBatch` IAM permissions!
diff --git a/eeauditor/processor/outputs/amazon_sqs_output.py b/eeauditor/processor/outputs/amazon_sqs_output.py
index 001846d9..5078e6fb 100644
--- a/eeauditor/processor/outputs/amazon_sqs_output.py
+++ b/eeauditor/processor/outputs/amazon_sqs_output.py
@@ -55,7 +55,7 @@ def __init__(self):
queueBatchSize = sqsDetails["amazon_sqs_batch_size"]
awsRegion = sqsDetails["amazon_sqs_queue_region"]
if awsRegion is None or awsRegion == "":
- awsRegion == boto3.Session().region_name
+ awsRegion = boto3.Session().region_name
# Ensure that values are provided for all variable - use all() and a list comprehension to check the vars
# empty strings will trigger `if not`
diff --git a/eeauditor/processor/outputs/ocsf_to_firehose_output.py b/eeauditor/processor/outputs/ocsf_to_firehose_output.py
index 2d2bae1e..99de9a43 100644
--- a/eeauditor/processor/outputs/ocsf_to_firehose_output.py
+++ b/eeauditor/processor/outputs/ocsf_to_firehose_output.py
@@ -97,11 +97,11 @@ def __init__(self):
deliveryStream = sqsDetails["kinesis_firehose_delivery_stream_name"]
awsRegion = sqsDetails["kinesis_firehose_region"]
if awsRegion is None or awsRegion == "":
- awsRegion == boto3.Session().region_name
+ awsRegion = boto3.Session().region_name
# Ensure that values are provided for all variable - use all() and a list comprehension to check the vars
# empty strings will trigger `if not`
- if not all(s for s in [deliveryStream, awsRegion]):
+ if not deliveryStream:
logger.error("An empty value was detected in '[outputs.firehose]'. Review the TOML file and try again!")
sys.exit(2)
@@ -192,6 +192,8 @@ def write_findings(self, findings: list, **kwargs):
e.response["Error"]["Message"]
)
continue
+
+ print("Finished write OCSF Compliance Findings to Kinesis Data Firehose.")
return True
From 27de09205169c7699a06026a5a3796024f743b6a Mon Sep 17 00:00:00 2001
From: Thereal SomeEODDude <46727149+jonrau1@users.noreply.github.com>
Date: Sun, 4 Feb 2024 00:38:04 -0500
Subject: [PATCH 10/10] update collateral
---
screenshots/ElectricEye2024Architecture.svg | 2 +-
screenshots/ElectricEyeAnimated.gif | Bin 289002 -> 277745 bytes
.../architecture-for-github-thumbnail.jpg | Bin 159782 -> 151991 bytes
screenshots/extras/ElectricEye.pptx | Bin 937333 -> 863929 bytes
4 files changed, 1 insertion(+), 1 deletion(-)
diff --git a/screenshots/ElectricEye2024Architecture.svg b/screenshots/ElectricEye2024Architecture.svg
index 180cf7e9..ba2a49ba 100644
--- a/screenshots/ElectricEye2024Architecture.svg
+++ b/screenshots/ElectricEye2024Architecture.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/screenshots/ElectricEyeAnimated.gif b/screenshots/ElectricEyeAnimated.gif
index c9c9aadf03b12753d9b7e5b9c87c104611cc544c..d7fa5efcc8a3ca85e388cf56974a0148faf6eaf3 100644
GIT binary patch
delta 122198
zcmWh!1yIyq7ya$h>C!9$F1>VjElYQ&bho6myGw(B2#A1)NH<8gbc2+%NT&iKQtE#{
zznM30-kCe^+&A;?+<$qA9s*+J(P?vw+s@n>WS6D3d_i_aB~Ys3*<=YE)`Dzi<4DY30kj2awRGMBAdyHdBzLS8a*5k1!YQBIs}#y2y1PYZIE157qhyH=#@Un_5sp?ubB^nVZu5d}vSUdFj&TfpF}3KJ;h*!iv
z!-0{Ouvdg|K1n2tc4(
zP_3JTr2`0L2?Di;%E&AYpL2T+vmj@nz$O&P-#pj^vNq3UAWJQQELt~!Rp|}(oLiU>
zfDqQ^x3IL_V3%rZd-7Q#hEuebu;>5I|GtM%_+K1r{o@4Aky#rKmoB)vFr)%rBXd6o(mFQMp*;>C>{J5bBEde1`kIJeU0B
zuw5;=i=|`zzp%5;ie*r5qsTx(q4@3
z2nV}HyCI_wg?p%eTmFcrQ{?+GLLKP+VU#|m#($I@WsM3L<9gxU*oE;uG3atx+!=;e}5o4E$|f_g|35O7_H0OrIBp|9;csB-uv(!%VwXWaZE1WaQ{YbB8(uX-Awzu2Q1}^4SGae>6gD%I6
z0d&oy{C?ugZ^md@;b_NHo^)1joZ~;XX_Q~ACXY1s@UE-o~?|%dB3YWu~
zufDBG@{f=umXc`SJ1RjZ7E1^BNu;f(0LX+o
zm;{CkdXHe<`AvOWWR7Ma^bh}Ct&|5w7Z3eSR>r5+%R*N4Ide=~q@}R4b5+)8Da>bN
z43*TTw@AH!dB+It&i>X(FQgARN&(BTp&mrR)tKT95pC6`fM=*O$6Nh$oW>mzyv65`
zAqWC~rK?hBDW`e78J%ZDIB#IbWnPdvvlasVPN
zaR5vI{3!MZ1O%hiWtI3E7k>=BMS?ZzvD|4f&CkDlyEsx@-Y$-)#lgUP5=QA!Oix0)
z2OUli5?;ts20h{!b3-H~DI9GRNBlSRh-^7jE;=BqP(6#_Y=gjXEsPouWZ_Q9a4az&
zClY-2O=DfEy*B@E1|kaAl-8db`0Anmx+gG!cR6R0mwEg(-Yg3`GI@cfDCtGOlp}tt
z)Ms9^;MeC=cIcEG6A1Vyh0~7!MZAyEwm{a$OYoJ7yOmG-)ft4tV|nQV!^c%xo`|nb
z@FqLr4EPPFU~nThnA1E49%|7%(w{=W;((#5jQLzpL(wg(>~MS;#Vc-H5Y_IonZeu)
zF4Dxo9wa6oWc9PmhcTU+KxLA1N0_du#R?Qrl!AezKc-U;`$YE7_1<$u!L8bJPn#SN~ANb3d7IN5m^*;E>
zb5zl_c@-L7BcIhQ6rjyyZLDmMVnpB4zv+ay
zfLIy5%2?b`k70kHpb)VQjc?BrZ07Tc$WxO{`tWg$OCbyINNqrtoC%M-8Cw#)XIX2!flNGnkFySG2TL&*C
zn{^;;xv8rwNajWJzKoatxO>*Q|LL1e^B3*!>*F{saGf`E$?4pMMK101>6(;+L56+#
zMK6&yJ91Tqk^Q775KC^jHppdb@I$gutbe|?LlO7r2A-?%&E3F`$m^!{8XCyEt2*<}
z&xkTU9?FBRrKJIbbjDr|4?Kp#JhcgZLW$IRQA_jahZ`1n$z(APuODl!CpYn^xL&GE
z*(t?K<#a#ae)tmiakE-?B}cEoxx%{sR^@40m&z{jgtePAD%^O)DJUQfyS%oOJJ|J6
zoTla@JAFOc&3U~4Kd+QnE*Mo|dL5YO`+rZPMyh#eJ4Lx%ykAWmkI+`cx2s^T)mF9G
zK%cu1!L_&XdM3i_w~2UK-*eWjV#d#YXg*zPsa)sjVH*)j0f?{S(`rM)w_ml9nH8qv
z=-;xD(5;5-qIkPv^+FR!=zHHv7EePzpQ`&?2GR+F2;c~L6A4BnA(d@t+v1u32C
zZ{Bs_vtd^ou7KFelFc*;{n)EG|Fx4?0Q_4OQIg&I@o9Du@qUHNG7Uh~gYyg&X>&mD
z+41o%LZMYz@uQ$I_1%IB%lDFL%R344%DJF3jGTgR6Kdpb5drvFXE_nJhpx$PFU6{z
zz<6Q)^-}{Ujk3yb;SU@C@P=Xs;!!{jx5ACy%WKiop^#_ucwLt!rg6UD0S87k=0&bx
zRjy~BN|ou3%IN{IJRvZ&<1qFiA6KTI^-
zeejLc2;scM?JN|93{k@(y)>wl^1#IM_?S`NNRCi1xUiRnWx&3+x=MfpEr(OKCqAnx
zQCyhEzJndU@7F~$;YQ=bCa;GBu9I|fT4FW^C;~4Df(S;9s7!Hr>~^!)p=gLxo1g@}
zR_dX|qYrxWx8~-AEQ#f?Sk_pDP}n4AELk+W{;+?c$a9_0xcFF3f+N`b9d@Zqm=Xbx
zW@B=pv*_~xU@RwPqCI75C1pC1Ui#*V*gkJbDEdFwR2jNdffj!0M26p^=qqpIwLw;X)FQveio2O0!gf*0I9G{>5fd9)l9^ACYIa}Na%k7kw$cz>ZfOC
zky)Vb=|pcK52M9-*@&dSUBwa)_-h}|!zl1oQ$bxLdV@p!>p3Ays;qpZ>ZtpNGqV`bwMZwpcPBSdDi{qWOJ15FgOMj@U-
zAz&~I=tFWdEpsz8bF(XRbCYskd*o(FXT|^UO36(fa7h`tl&atkRT!h6xy@_1%Udb5
zh$-R?-cL6e%g|X6e|RSq)$)c>{kc$+hE@>=770rPb4(t%_GYtN62)01hQ_RB0XGz)
zzmh=4$&Xg!`CB5I!O5&)@hDoAWFdzgg07BnuPoo)
ztb(q?-u+H`_b2xqF&d;|N&he@qOIt4RNLbRft)ORub-<+yJ?6%_Xo)PGHLHK=}s~k
z7_!I=9+07NmC=zeo=OXPm}{|Vx3uRcNb@sV^36z#(?Q{CqT)VmD3rRZP)N+nQ)I@b
zH2O3)t13X|v%6&AohEqEPsz*}L|AZ|R8su2uvId(NHlH8s6g*Nj(kWosn|k)w$%2%
z)SjWtk+_UWC>KYI-c~e~bv1^;iTTp4^epMk96j3?LV5x;D1$q%CHQfv~WB{Ju
zEC>`{7Blx|O|wM93fI67MC%8l-y$*?%p*-GuHl9!`vbpF0G@Q=yB*JWdopzgR&__7
zbvspfCn_amJkC2Ewd+ZmYE`9Zj><$!%@?h&OTr4=1NB3cB|Et)X6#R@qk>g(zyJ!aE4wcg94dr`$l^u)j&6L*z1D;F1;AME7Tf
zt!7p25GaSC018CYX#@Gn7N9h%;1^yRJO1Hk@I76~J#H=p&ndiF<6)V>MGgx(>KnBF
zW?6i+GF2z90Q9>#9T|gCZ85&*k;)XruWD!xe^cf8)=#S7#eqRz6F!xj0W?xt&#+A7yI#NNRdyx(9xD(M;5RpQr?6>!ZV3^|d9i#3fopB_-o1*IUlp
z(NL5tp%U>)Lka^NI}{&Lq4n0CT~*`4bj!(*Q^l;l$@H%&rt->RGJ(DHmo0-u(q*x%
zdNjDl%#$M2=Bab^o6#C^_UP`FsRPfLcH7mu<<-zObUHQ75JZX%dumr+>wwbTWdnVu%rcd;Qf>DkF{y0
zQVST6Lb9UGi
zi4jSO*dmzE8-QNmCCCT|DaUk@)IBMDP{mtfxMJ_v(!u#zMl_g+gr;q;SPu7dqQ_79
z;Vd`lR=f2Rt`L=uhXZZGH@uUXY8VtpYua9hQk#K{7@tETF0lVJbTTmHm&kcWNl~5@
z0V(*lOxH{droz$T7^E<(9Pq50K;<)u;A>be!RRcF*|oQs{=PQ6Q1)E4FK3t~D%<OTL8)js|Nd*{m9yD6=3;qn{&}2@{ArL*FoV5?}P=o=B!7%REDq5eN-}#WHRU
zaBu9_DGZu!0P(+Wa7M~1@PcNde`9OS1A+?{Z=4=AM-Q`d7Xy<(l#Myep=HcB@EO6z
z)SUbj_C8u!R>Hxm_A@`n3)`h$;<%vFtSo$+$+fX5R@_Ln58w_jxHaD!{&
z)TRW&RNydheez|CO3&^1)yHdbTTZ{eSr@k_<(_M7
zs-uHi&A7Zqd$X%*Pf+mSu-Rf4xIqX!N2j5wb%R8L{BDlv4=#NlPb@{R&L7SFP)=|3
zz@RRiKN;k0fctEVNFbH0W%5HiSE+GD7ja)#!*@;kb^Ez8SG*mEJkuA7#;(ay4t6WL
zUU92TZL&Updz+&zt3O-8mz8>!)AnBK+)L=fF03i^bhzV<98lCgK7Z{3X3Q$Dxz8?;
zqp=ULW~#1tiC-kB^KGEsF5d*+cc!l5>kYj2zjcXx#ih2BsVv&8xGWy2hyPI~%jye<
z&fooIsR0ir3AI2D)3|TEQL$_as=Ra+$~-1Whht+?_BNMR?P}T4+>BQuW)hT^go4aNEa%scLQVuTdbR>$SD6L4r`69>L(yOhx{Y#Kh1KS
z@Tlxo6-6FpBaeE$Tx|F%>cT)tYr>fcphi`P{eSYJepdUohstVl8uCF!NW<=`){f1a
zVV%2{)?m6N@Nbc(``rkFP{RLgfF0d9ewYvcgK$0OTxQfIROm8N<=PKVWhZ7kOj*gY$1w>V!L^e>szP=HwZjBwUGb
zkLYxZ2(Jn*OW3HjLqK2;TCf$I`_0RcLa+B^-w;I+x2z;=7RdP2w`w4*OZkBL?tCeB
z%XTU9F9)iqvL>Jk&(Y^qB1%!O4ZJ-HLP5s^6|8T9rPRwjlNRQ=~Ko46fi`*
zJoLha(4Yt)j$zrW9YYr(h+^>&^g|Xx=E}s%=CP{Ne|@d*Fkam|H+Dj=}WAq{_gbfiG0t%P7(+la?>X
z$YlZ}W*W^@5m2c1!E?`9p3X^iAT+m>w_34f83*97<}C2=zm`B_6Zr0>kiZ0@iQ3s*txB5`7^QF4))ZSXPc-GnXsP(3ZqRWHn?Uk{dN5|m!
zFSLKQ;=d8BW4_vVX1jNSgzV
zmP4|`w5-3G76X*Om_%#R4=n@^!b%xv-kl
z6!2oDjD6mDLeW~9jWa0=L%m=7o65Xl~{}c>C1lKs*6Bs4*
zn<{(Cm}qt3FVA~k9Kd7X!7^Y0CS^(TT+8`&v&oCWR8hC6gtYQW>q7M*NCO0qxJ&ECP(&oIxwpu0Rk_s97F3^
zkGoAOv+VKC6lmjg=-Yrg&y&8?k1}xF5ZHXO6Khw5&R4|;euz)Af7r!cbKjlPZzVjC
zqkP9g-q1&dq2hN$wd2HJvl$*-_qj-^zb?)hW6OOb?OACm3&e0?MaIbw6yLU1Rx%Og
zdDOi45#YtwVo#dsEis&-U3AgvJt^>EG=fU&gE5c&qYg+{mu4Heh&IO^@knEB7s>B=
z%P_sHl?4F&mtXJE58V##OlfiYxjb%^%-7`uFmy{=yZ3kxrDrVB<27ekuG7K!PoG3<7F_@ODyUe=q;4PG()6T%NlRW|N@nzZWzaOS=N+NDE!T??v-y0prYH
zbLUacvKqH0D7Q{TSdm@jEq8
z8-=(|);~#5)8A8*4U&Vo;^Z!Exl?!z4j5KaB7EA0zF9^@R~>sYnOq?AsL5@8wOm@f
zeioGULz65*my~PNVNGenOsN?bt0e(qdQUmhA~;ft(m8!&|C@DbNH8G954>(P{okle
zo%nHdafBg}fMh2d5ix#531hF0lr%}Fp&n+h5LPMKP2`)V7td%rEY^mYR29*Cb+zHr
zAk{VVk{lm1zgcjPt7?RwZ14e7!h*MxK*IQm>KSaTDE=v6J(UErvsZ=~ei(QbMx36*
z?IQF96~c4o@m=rbqy_y#tmw*1q0Bb{yLSPOqJqC3WO%SMQwc7!c9V-x1tsqtOhYVl
zlA-fYv6xOY;gj1AimJ0blD#61ug7__ca!l>DO|E)cWRNYXBeFYdwe;NRyC#!L1KD!S>5$4NGusSm1psb}P_Rczc+?V@Xt
zEwg7{m8+VRoAvUk=(eW6RA1EmPt%VtXpsg*{Zo(EaM17rTE
zDNpvuKGO1Qbc-vW_EGGWpg>hy(WGLo
z6p4M0DM+>n8DU_RL_k6)g$#gT2AR)<5(N2nBK}n)sH<8$1qqtCsePF9KcQIEhnG9F
zsM}g`y&owKQ#(*p&S0_Ok0hs>UE()VV~jJxsr-=+(1n#zCT8KR*Q7g?l9ofo6vByE
z;goF-#oU2^iW`;Ms_iv0(~+6+{hWIn!5U*lflWkyd6eNk$H?JC>G5t^;=`xD4EWCk3cgo5AvA)@b^{CvYYL)F98=!shBa
zj|=yW&|iB({ksVPg%1gDr*5o8j}^c&Fo;@r^5*w-un27}qf
zp_6YjUy+c5ff_yS)4A{O=ulsd)Yb1vmB+uA{MK67Bk`61-OIE`D2NbB-d2-0F$K
zgtvQ7MH4LA9Fpksok;@EEWCOATQya0j9n6!udhw^L#9GDf4&neokYCj>P!*E1$qYbVM!3c6%L3G0T%1SW$eRo?!#wCfVA{f|DlbG-ZFj+8JrFUa1qhnjq@TvQpEjtUF1DXGHjTcdpP^ZaHZqMx
z1I;qq&oTzkZS_AQMZ&I>Sg8kC_xhQ>^>fG}S%L;w=*u=7P@Pm8Dayhnu52vv88Rlj
zbTvGQ>>ZUOyVN{cHTWw9lCuQIRMgoW0D&J`B6d(RYcMRPO}cqd%6l-&aS$xKhgJU8
z(XWWB0*y>Vu&W@h6q$6;OeRArDnqJ4Lu!ltq=+F+ogwuNrGGo&pOhvx<>{RIS}WFZ
zHvV5SZ%a}4)TJjw^X)C%M#=~le1uK{zCoq=pF!gEVf&)ths~;Axrc0P`k`0D_Cfv1
zCMtAj46})fv&o3F^Nz3?}UBZ1W0T`Lv_B7
zX=3N?85=s-dGx8XI)g?(u^&3iNIj%k9gH45lSS1SRgFe?k49#VZc>b3td;E9$1suP
zbcrLbB`U7gLoOvMagiEoDkHe`W%NA#0k{BvGonloBX^Oc8wTzExX7xC-0FY@3CZW
zlt!7ghK3FRs~O=|(X23#^NHkK6|PI5RCWVb@5m-r*Cdax$!$h}<)whve>7i54im48
za><~Ztta1Xq;&p4Q|FI`JyB|+M&B^@
ziW{!SK3Tp}MUq0A!6-D7Eb)#~Y~!9EmD@R08Coyd-jn-Y)f)mZz*9-wb%9wNkVZl{
zx~Q8P-RZ5poUi-->h0&N$>}l8&2I|pDGY-u6G|#G$g7Wzv07R|*a=q?jl|fgq>X-u
zc`D&9wG$j>f3|8;KzZwaDtMuC{j#vSt9w2&IZ$pgHx~dIfB-_h>9O%Qk&`H%(4w0m
z@E3NnmF7=Fk>rC`*61aD>pyl@DYc$*$(nUt9D2<=
zZ5;FV=P@EintEba!!3eMdxzv#3Ng2pW-dm3h;_D+bY`_imm%Enzm1ff=E=>y@y(7o
z`qJc_EKo(E;ciMUKH1O!sfrIuBbqW4L+Os^1Dhg<({sfgU^1D|4$`Qs(I76Jslx58
zwk~Vlp_h$*<>$pGa$nE~ZxAswoDotE%F4ZoHS8++bQd|GJRdh}xCypX#DxJsphE3>1x>8Vl>LXe$W3%~&
z!^C6u$%Zz>Cd0X7h|lw3pH)2I%No?v*5s?a(+jw!N_U2`{Ik@I3I2%~dtD{3c7kum
zpO^YXG<(4Wnm;SR}a$rhuj9M~OT2wTdXQ%<#{TA<%76C$Y_Vju7()p9v3H}z7
z;O|QA`D31odcT?nNYSWh)`n$LGzgC7*r+g*ZQW=!+
zj24_%X@gb`#+M#$EYUB<%R{35ep$YP6R^<7(hDtrcGo#cL1`Szt&I$+#9z%n-|(NZt|fK4OWvh{0K5A<-a`=!++8M;AHZ^gH5vyBDlNYSs{hBn@Qre&}SQn(&IX
zVAx~tiyQww_fxXM=||==_SLfH7d1W_g(m&`gXmfLncb*C76E
zR1&NaJUz?PGxKV-RY+A6NkJ}gfuk;MYbn2p9mHl85HTD&)Exv<>tB%VY9^5&@FFi_
z2<>A&P5{C5>w8hQhaG5=6?%OG0w5N%aA_eQ6OGbIjD8=n`tsK#wV%?*1@zc3b54)u
zA0MT^`(G=6d@Tp;X{qgJ$g&nxZB+jb(j_h~b0ks{;`sO_u)_&83F8c47&Z-)&lNKz
zQByp_CMS{R6B|P|-&N9o;4oKx#`SZkl?M`ZvuNu$;1!*v?hXu3t8k7SEII)K;ykBF
z4h*Uj7!%4XShbR>Fyt6S%Fmxz8`o^R`*t(wxhAu1tIT~P;
z#zyI;Ea^ybSRl(P!Wh~`{HKXHlq*{XD411#Fga7V5vAJlQPx;RkXrEDDOn=XozEKY
z2dE_j_Z@+=0S+Nr4lK}9Q0riL(lHMWK*44}@W`}-jtxU3NNEL4?iWp-6ALC(q@8l6OvHI`;9Q(KLlHmg
z9I3;%Kfk5wLR90(!$)t%Ku(gbLwA;3`-Vr^)m(m)NGx$1Qorlb4Px(UoA7gjR{9
z4*!ZDMl#0w8laUD)k9k2A5=suHN;bAfuQJqHCH8{BXnE*XFHOhh&F`)juqgI{Ag++x8}NNbN2Z9C9ls7
zO8?%g2|tQ{<`rV#juKt5*V%MtU>`|RQxnuRH{x`Gt85>Mcv5+jDYg?Z|Hm>xPA)0?
z@{)u4%!VLg8vW+y_7wgBq~aJyDUQV5qrHzH*#5xvdd-R{)4i44EG3Wb)hGW@V!qqK
z2Zc_%%)8|ffRX^9`lv*WB96z4^dHxWp
zjV0SxW?|o3P-0F5ebHQf(b}Jabe4m3UrhR*+5N7)(mT8|`WnP{8$?5ANzW8)%=ODy
z{}|r8Jbm&pUWGbD6(yGNs+2Da(Z?IJL(@YTgp)cdwrCHLam
zh4n?$`v+XsMi_MxDl}1|C&+zQ_&PKlMPB}NcVoygQ{VIDBRAUSGiv(Su!flM)@Vm_
zfQ%kDDiMVVf}e&K=+b0?97Dmu_+DzZPib`$+$E35D=j!N8vs>YCi4pb*TMBYc+&0jr<3#M!Bp}
zwu@A0Tj@{x!>#+Ii4L-(al_a%7uP;?gnIw#?q<~#4BB9pSG4MbsucqsNH`?sC+Qjc!of;6UMO5MsvmerYpqY65{YfA{4h0
zP~h0#EPfz%2s$(*fv(|+N($oj>N&)DJB3FuvIYCqLY(vhX97Qwl;Kk^wL
zHPP1W0!VRX1s8Ip$s(ao&wAURko^8#TEuljKfcq0UUvifo%?@z5kD3L%+`4P9Pghmtim`VOd$HajL&ys
zCyQ0)O}^j5cX?+T?k48td4E-#)>w6zT~vvFv*<+NK?HPe)oAeIO-&39Eilp4#)SHY
zh2S*t!FU#@&pJ7EZqsWr>1PIPVx9vX$d`mPJZdMOoT*4P)7gnqSd^RHyRz9)$}&D(
zEw40;Sf+fwD5n!HPctTELs~qz3VnN8xAF-X#EuGq!TE1HqnUzsO{`P$BuOgMTU;kS
zIAvRmF0w%Tv@`fe$%dgn)s_Q@z{(YK6VF54j
zP8)=c!i91rS(7-h#4TT_q`Oh?^+P!~#W27%5due7-<@huO8O*+EmhhBmi=6@AMW%*
zVyC@0O@8Of$zEwkti(ihGtoIiM);T=s8lLbCl#{*K^fyHiV-x5#4sG^Gzzs88nG=Y
zPLWCs?Yg^O`cob6_xq0VUaoz#k1aowfs`p7Vz>3^tza)>9}&%>hfpNT?1gymmz$&A
z={aZZ-RTc5%-ks#lC*4mlv6AgshALReRvj~_dJ&Wal}3#Wr@pDs%63ZpkAxGA!7ul
zo~Sa=VCztK&=A5k@W!9K$IO3tMhzOQX_KffsDI|1IIGAD@0@+mt!x~P8ek^2vHEx)qV
zn89Oh&%=VWCT`%+44uK@S)9tbh4d}alN2HCui^^`=Kd{QQCMQ;W&M*&Qeh~=xo5eB4S}2`(MV7fv^9`Wv_D=I)1lMD~!ewb0}8t(T$FX
zx(2-M&U+f7>*a5LOfc;YfA2aEv!t7BYNzrw2~hm+6?~rI-Jh-{2BO>eyha^$k^{5}
zp^18x7by#_75yT_)}YhKr4P44`3sJqRDWJBfojtN^a_cxV7|hA;I980`on;}XiK`*
zGec?2db1e3v@ulM2&v66pCRQJ}R{Lrkz
z!i-K-Q`xzIs9yQS{GF}%h>c?<2fi5#tkJ=jdkQ72+SN+x
z-s4ei31d-2nc+%Aw)WBNTXVQCwW4Wl8!F__4AV6c(L~p`8iC#Rt__)Asz$O0b;4Vlt|Az2od}1d=S%EUxV@-mq1Z4^$1rg0->K{Un$eHGNk}JTjIZ0|3u#}8wN>%gH
zW-yAE%7+`Um0>HJT2vA5;noRcSbTql4N`fZ3kc(eP7lnY@pp631MQX2CnKCpp}?@z
z&+?B!o^`1AIsLyC4rih^Kcv0X+9L@l9wikDAPn8(dQ`78OSvJO5#O!G{v|oqs9(S|
zmzvxD38fZYcH=7{XBQs9i2;Wwu~#%c`#dNd-qknMF5zu*m0?C&DS7rvpzW|q(wy93
zbC2w%f>I)P)yE24uV`D!X*}H%=5?;);_*#2PK-LJ5ZLoGICcSi3c(sd+TB7V>J4K!7)`YXV)Qn@8n}OiB6Ic?-7v&G9Rt|
z=vf;f$=CTz0*A7b2DZ~5_L=xDP_BsRj{>h=eyMR&x|xkVZebYz)yB0P|3WDOE9@cB>-m3
zTK!LG2gtb{#k2QM@nVDzl2Q)6N~f#xb&uDSQ{zj;x4|`T_FoxH
zdm=KuH;GxgucYJ<@+iL3i%aKR&Qp3^2j^KHKnljco7@5}L`Uu`vfMRC5a)bYi~#;9
z+ztvVn5KP=Jdj2G{`BCf>*%+Lt#`-wBZmt2ud#oR0z)gQ(lJc0;O)JMm3CP0u$>BG1{~E1pm;q@TlnGH%focNc%SeZ
zDUq;#TUFRfCCWD3@A+xm+M@UNcW4~HL*GSiVl0i?{aBuZoRVG?Iw=bM=z9AR`M{%-
z!5jAxCeL_gN6;f;N7(%~>wnuDsyQr6gsf*QFa<}pOBNQ^P0Eu;|CyqhR+LB~dUUIH
z4&SDSNo^dY%u`J1usv^hvvrD6Nl)5YeN=2hJGQ^u^(ol1*1gS(G?O@N!4`x=8B8
zkuVrm<>ByD47m1&c6;X%TcC;UK?Vp6^AXFZv0|KAHr*9Ag_B+Vi(2L?5uQ5wl~?t
zT`e>5A%%jzE5nHElJ#<=t3#}-o7SF%k?maV!20x8o*}^0vrj4#@R}KfvG2E{EOFFm
z)xM1N;SRk6aA$D;a2ATkIrOemX>Gsfw(`kJL)ti0rEEI0!bGJGbR97`Q+q+#1y=?S
z@PzYq4QvZsERmIL&Td-G`ys<>B*(;dR8%
z0vtUD^eq|ijV#xB-1`Vj`gkHyXwsp+KXLXkJRB)g`=%*4vMc?#LwzvxLu+672#7Pq
zFd^WP-f{pZnor?>x^$GxY#l;Y{XkvHca7kab`WI(HAk!DINsK7FD6}cd$+TGE09`@tz&cr8Ks}(Es
zRYf}nZzf(++D^qEJenutESM>pe_vAQUNCJxf5uw8qf|Q&*<6Jg0mwJ@f*2x%e47*s-cr(bXOJ!%bx?)n(P*DMx%~
z9$g*C)`;~EG}DWc=boln(u{`y~#D>m$0nN
z3BR8vio!x6sAci%E21^GeJW{G;LDo`#=}BVWiedv7e&e&Iar
zuAN|t0|eo3rm|0g`iv2EZ$8I5
z^?lKed?`l^9A2jU?YD7A88nugBOvVK=_aP|$QKS95v&zJ>B|a0wFNu
zuwpEeN9EHvhN_?dbzoDe@0{E@7Rm6Gvhuji*|tn1y!`X?-8Zi_np}7+H0B1!PW`OPS3(152NS2>cFJciv)gpWx5852?Uy(^=(VK6?JkA;v3
z3lbHGB|S9LVn3M29mulAv-hPQ)Ha3#HqYLb`zig+l7Ja0n24n&GxAs<~SOI}Hb
z{FGeAsD?Zg8OjS!4)`_Tke87_{`^NCp}*ZDz
zifTpEEOW%nt7Rv$#XLdW;zf(aYjMkWEtcitRw!``!9kH69P^l9^U)S_Uh=;Uziht#
zve*^3I}f%UZLwPrw_gr6(+}n}`Nd=Mi+xYMj~%W@-VJ{Rt>%7Bz%!_tEhI`wHF%tt
zM1C1CY58=o06G*`N6FEmdm#YNtJ6#1Kxys@0_;u16&&&6fw~4ijk3?_mWTMUqQAyj
z8-n7qo)|Z)E`w+nm1>wI1Gw4(1SJC{+X59OgVZGhiqF{zg%H}3Pu<#{J_!lr?UVEx
zP<<>$J7h(@2S_MWpB-<)f5tjW(Y%))L1BDpQEDKkIP#Hz6XXU#ew`EIEPL(>HFGh4
z5`Ugsn$_ZjhL~8k^e*HBfmSxvj+crBUJf
znd#GMx>cn_$FrMf+B9zC=IyOD6b-jaz7BG8bSQs|*b+W%b>a1Cosr}kndl+7OE>rU}yymw|!%b%cR;G?FqHaN^p{uhIdtX;9BlwLJ
z{H~4fPJ-)y6rEK-6igR}H|bcqap~@obm^4tP+9~;P!J^CT|gRKIwY2o?vQ3F=?0|*
z1U|Y|RCIs-+qs%^G3U&@^PcBep;_zD7msjcAH_cgc76;whYs2jCIr%jc9INhlN5&#
zRVflRDS~^?n@sA#n0lJq){58C6wl{we-Bb!AzwX=)a2fV^h3I;()s|o3jO!G`uUUw
z#JUFX1s(mx3WM58Lq=Ug`bwYVx;{M!9h3_lcDWsn2puZ>Jrvy)eNU;nplhrwbnJ=J
zr@)&p3I8pFK2E3;Y+iy`m3--}ao3W(Qr4)6`KgUhu3{=KUr9u%sxLTpewn?*x)wW7
zyhh3zO*Hp@8H~7s$b1|hB~)w(RIXPK?T=7edKWrkcH3C+cQCbUDI&D)UD#;v-<9{F
zYwyD9ghK1o|H#PIt~onhSpeCT#5V~|N=qO0D+bCmMF495+%KX)jP>kGOs^+U&tmG<~T56k`y$>A&Xdk>My
z!+||l+M$QNx2yn^C?a$`u;(T|^rsviuo>pB@NZ;q;}{2={;D#(r+R6~TghFIUC~C;
zrG0Fkrbe)O0C@hdi2}II+b~Y*(UcroY4?+zHRBm1+!xxCU51muC8~_@lpUQ^9+P}&
zdDQM0(4V$3&C=b8=_%L)gd<4V?TD0fQbS=d4EhcLrFz!N`f|N2zv>W3THA%Bz%CxHt6gTjG@cAa!vW6F#`majxet~EL(Yv&Do
zJ7E@;Wta8#+hFTle(ZRbBnr%!zY|nk=i@eApc+lD+)<=c@j=seH#YeDawBI0&`~}*
zskzvK@CG6HEXfeyru8F6B
zR+CzKD&Ga%e^HV0{prt&={u5w?Uoyq4a-_GotzzZOD+r`tN%;nUH*XV)C_1qbmTIqk+U1ithet9$Q;l|RL|r(tQI4@~mPhX0H_6$)2}mB_-dn2W
zc`A%aDns}eArfERTv_M-*WVQo46P67URo}D3(G(`BwS%%g@P#J+OI3rN
zOeX?=ef3qdL}ztk*;qLvT~`@pBBk_eE&XVfT7H4#lmN!38r_qY*2SFD(pUQqbbxE6
zb3y>=hpRG+Ci^BP?;CE4mQsiLP+1!n^`z`#B2i-mkPnFg&Ybj7po(mq>Y%czaw|P{
z=Y6_nBAQLc*BKg3R<;+yTIu0k_DKI+i{bi|Yo8MSGd6_IIVPuVfniqpr>EAa-pBH{
z>G6$YKRqn$|5NpQ__X5hr(;Ir`)Ayt#YDoWZ?U>NJ)2@*F<06&y)uAC_~lzuft^0BIed{|
zxCS!CwV2x|i+5CCCGja{kP`%ctvL`|0y=l@ydZR>U?g&nqL_(Cv+Pd^Zaj{V@^?B!}TBuDMZ4CpJc*pUn!ccK%Z)h8d&h
z5Lif7v?@5*I8xNSkTjrN?F0*&E_bA(r1Mah2sTOFFauxV`m|#&Oj!N>^ND2y)Qu{Q
z(|M(fXdK?^=_?pzgZw|plnNl^J)_-5no9mo@M$AEj6z6SN{5(7SY4hPl;S&dk$Df_
z?)|8bMQEU7ozdP#at#cvwk8S6)778eshoOuF@_G;1*$>?BhUoq
zwZOMt4#WT}&}IuZ?EBGUAd7W}UYdk8?AQrh1!O8mvvJZLD7oUS1`RCg0pqp^-2Baen#-v_vZI4rvVK@#$##Ho#CZuGNnp_;i-tO
zloKC!aEHTH(U;od$*K_2!|5r@pIv^7qAvLi%4yvhy~f_o-eMX;UPlhTS??;>)R)Nt><4|Yh|7duEo4oU9$?mY^lAjISUYYx!wE5szGuF
zr=wjNby<18UVxxFR<6n_eCp>X4lS`qJa)oPjjg?!pHibz+uxG@p%)>46uZ=XIQ;a-
zt1-@;%C~=SHu;`U_wjMogB*}LDX&}^M?sEH?AKmr(!HY}K5G%R4>*4G`%`;&S~4(C
zp7d**U`Chc3_uZna
zOn6x*;L!M8&O%|W7K5P!xkX*hVw%89$r`6b|3QV%bT_J^?hn0ej)K1++wn;)b->M3
zN6J;ceo@&5niMecIRZ51(+bJ2@qVgp2a_-VLGS|g?Aa5$RhIqMkA2-hz974$5!D|G
zNr~Q%{se#S`P|aEJb7gG{%l=nsu@-O
zoti=Z*F!)QkXGtb-L=Dz8U<{oKrE7g&?<%mGM4n#F*l!#12@BP37P+AQLFZ-CR*8y
zj}8{WSaq)O#R3Jb?rj8GF9m<;HB6{~mnUKB0W4E?AQu?vUO<-d2H-1g@&dc-Ru-=e
zpFq_L$$HD0xMpO#whB0as>1mf;Y+A*&bd2O;(Hb38eh5iFKJ1TlRBT&G*%hMPpSf3wcI8C}w`fC`;&fObryI4*dcF`75hT>i_v{)^L0kzWZp1SGrnq+A
z1eS9!U<3%9H?KAbF0djO+>T%}qh)Hb%W!cbuCt4LRbr7dCfVoU4A@%!%oU=JWHC;h
z6+nVSg*7#x
z`J;C`C$v9US4&0#z!=_oz@7AjslFIf0&%qjqMNY9<{gqcicNYy35EbahSw$xYzVig
ziWa3Jpe0APAc}wh{VgBBq(i!5K`EmY1o&F@m|4bT6Q*nvw|oiavIge5
z3n|G-u=?al2OOgBd#WPBb~1Hp30t(TUu3+i1PG>b)pHCn(Hj(@{PsD85sVvgiG6la
z{p^xrZk6@jWzo!Ke+`G?bFOM%&M(BI1qdjwDpdLfmwY3a@+FtNDLvKXFUZ(0B)wq+
zMQtfb5&&hi2dAigHBHXaP}@pSdwB-X^^qXaYt-?pqt=nx
zTM`nwkavHTB>3pKeqC4As$h3KHU)=`gf0&M9gFb;jq9BK_LO|ciH*4lXX`G3VA>Mk
zlBw#(oXD!A=s}~%2{jn&Xj_EDvPUL!#hCzj@hC<$twiQ+04<7<7m)2+!
zLP`SaD50!A-veipd$zD-a(aJ$VcT!fcoJ&yP+D7x)P3gc1(4lvlOXwkAPvaw?sy(N
zLr6EhOfW}8{sLZja#3Bwaqm)2UhIB%B8k8YPPzf0Xd^fmA+Ly%e~-M9FO*U!y^_y-
z$uuKb$BN((hSzbEP(wNED7Fs_BuRZd7!P{lSc-2X2BOf-OOmBPA)~
zI#vG>T!0R_>huh6Kb%n%izzdm{E65+xQc)2AFa;rxXKya$M
z5n6mWEh&(8K$|wCT3pzKSeh}tG6v8)$)FLk
zcnJs~MK*B$oY9Dw<=rK#DTxT>710%ETq@_g`C|nHC5!_}0#l{DzBc?RP4fHN=w!hN
zEMqLQsXz>;3amb;-xRDk+v=K@+^OWjPyhH)$_-=+78+Q^=D}Y@Ax6(m^^Boksm_Z0&+wJz1JxW1_5Lz{sIt}2%=OZ;|2>nX6eAoo
zhkKd9dBiUBotW~soSMj?&4nNYPOcEP7TUxSD}^*vHImqNe?39LGKn;V$rk%kKZ=&|pXN!MwJ98!+8@Gqp^5FpEQkWC_)Y}Lza8!Ye1GiuT9f)xxZxxb
zw6uJ5%JYpgm4<&e6ZnSace-BCLdS&O{Q$(A0X}2^+^2R>7WCgHx-KKGX>rfCeh_b1
z`XImkc=q3CpCe0KR;-wmGpx%(JkCT-ci_3)f(YoNNJd*QhepOW(u)tv&xF4X2wv&)9NKG-0uXUp50FmRQhQ--Wd7
zU7~!*L+x61?t+CstVaM1>b}Qh28rRmBg;?u{>0UXzLVPY#Mg=m90>9Pjemd)0ad3U
z*+nH5bE?HUKBKDIw9Mx4%TC^;?cCNsn8qUdsXz1q0=t5i6%^fw)B5HV*l4T8`g0{x
zy`r_B+a7RBU23po03XPnU>5e^$Be2z5rk2gdVC4|SDi{EVJK+?J#sn6Y0iLS^J?oZ+uI$lxN1w1(x26FYAQI@nq6(fLM0f
zSRUi^Uq*Dbj(-2hPcEl={gb5?Ox9M5n6Atd|nfx0aGp
zqKabuzjN27YKq)GBCCu23M`Y$bbs1Nwh6G@z=R
zYyndWHA2O#eN2#1d5H4lN#z#Q2LTX-lfhQ&2e5Q&%P)4RUb^|_OKbHKM-GRfea@IpYg1j2N0WT4TJn9T)#+d+NOy6W}2Yhhb5@m}3fn&hwVB?g&tOA)z=3vWx|
zr03;%b~uR13A7&zdW4g@usC}Wl>MTx5uffzZV9MG`upS4SqoQKp(J2w`CM*PnqI
zO8X90fBzz%gD}5v5LyV@>4Uh3fGrW1f?`OLu+&ef6|d0tFk>7WH*9pSkIfj~#`L^|
zc)HC_S0XE^B5ZjylXbdhyf&1n^NMCxBTJ&~=W5=c$-T;Q=(sgl58U-ye8Oz>y+U)&
z+RC!mD!!LZ?ILcSN5MTt6)=^_feYXOu>)p0)>VtY;vF`*oHt1~q;6Jw|FS%yv_me;
zB+s2uG<@}gJ~p1GD{i-+&&Q|7K;Z-mA^k#K?FO04WR$T(3#<^p#iM_+4|CyO2!L=a
zfoJzCm#)@va;}`p<%keyWj!cIc~})&k+1)7$&gDJdmx58DBJ+`*dA_S4h!-R-~R)Y
zJUV*baM=0pXv_Gh?B78h`_bga0WzdVvMB%fi^@?I`_a(G3G#w?13-H1^nCrzVQ2nv
z`@fU%e}{Gd*wu;;h4$Qc<|pD2rmH61v*F4qPc8!n6flc
zv=M|%mR?Id&hasef?fNj$V5)9gvCnW4UuHYNHVu3$^BSKH!`;c!?sXe5e7XkVW*zZ
zcK*_-G@g*SG@NrxBut5$QD$r)ud_H3q7$UGpS|Ee&Fu}lHb+>fu6PnrH#-e9)w|+H
zwayP-{x?b;ZcQXvC|he^^US6?CSF!-6iklwH%4utHu@q-SyU2`_ZzkcLjS5fg$Fh4
zjHU_M^(5Gw2?9xk)v3-oq_!sWgpd>>%sU8yP>NRiB~3&Il>^0_>^9@E0Z|&R%Qt>p
z#pj9rW?+oh!-x8r;|`w?Oy55E?~PSYDp%YOk1SeEjuQV}-EUgV(VT;5C=#?#mFFf>
zGvOGvfPv;B$Q3P-!Zt&GCT(u${s2(^b%I^^0*b+%&=HFuG?w;7`%xR}6#9kA5NRqW
zTZ}kGv%e{4lmIC?WrIM~AWj|56zl9*em$KT&!=mj`$<<=n~i1Ux-hG1G;St%RT&y$
zCM_WmR}EI}Pos3}{(Qz)>UwvjmG$LZ1;?iIj$d>dWCckCBjC_h{5u=pr5UmTDpfSUsyQ`u*Z2slTud#Tw_&8o|a@j`;2lU
z&yC?P&2T1hNq{7Z_mkSRy_z8fna}9a7tNi!QFs5nQF}fRurQS32Q=AzI9+I-nkv`#
zav)&29ft&y4qcw-Wv;}$PJ=v@AkDWldU|D`z;E4x4ha|LLMi@Am!U^0+IYe36`pd9
zNO35oo_3tPsW2mY&B<6E&ItRx6qRy1F6I=WuP^{4EbW=<5w^u}_Mv<5!Qg7jlArT;=UC!$Rb6A&?Vs}=vxInUnq
zm6drzra8vD$<=bm9ID}!nlwA^=w)Fkg!=x>di!+eu^sSmhk_K}GSp&s{$Z!gf%ws9
zYeFMNJ>Qk5V*3n^zbnZD*XUAO1v~}jPQ*QE!aJDDZLA0UMnEm%tHa&bSsFr5({i;)
zb&x2gD1eqvGd{US@$L2zu~bQ#{+^*vZIiQ-tFJJrmIW%DbTWkx&}`Gtd7|src(h@0
zRuj1R(X344)GFkIMveJ#rO;x><6?*+>Gdf$e*~acB=B0`k;g0C+~aqDT{&e9mIq>d
z3eF>+qDU%LL2#g_&_-I0;iywWmoc;ED`c{<_&3#*gyh}aKYHYD$F6!ZFHI-*
z8k>rUhM+vYVHWtK`v)piYTE|_caemd-!SGInJg7v_3wcV;+sc2U#F8cQp9qaJl-SeyR3PMg3!95eHe4s`-fmY_&q~vO+(q
z28If#I8jBm?3Wa*mzH=QY?~GA$;gfiAHG)cE^*6hfRouwC#Q84_E~E%F>oBF@NB2~
zjcBU~SQj&6gH@qPu9Yb@({KXhtQNfdJ0;8nFec&1y4^@EqaZ*l
zoZ#e~z(dPUhK7F8ALGLh}%`PXUr9}Ktv&SVXyHw#b7K54_u!VCb90TwbOUr3N_aH`lE-{I{>
z919*!C%`6#pw>#d9%8`^@QNqvj^{&g?}HYyqWy{+3=f5C5_}Y4-eZSFPicR&4fC%6
zfU+;O>3)@XJqToG;6Of^%JYBr`mot5;?iQeWX~;`G7e)}ASiy`GLi~U@#L)#WHwHz
zgWA?JJ{RYO+4As^HpBm_U2!x-^^amXG9W1x
z3f`5qHo_ipiYdn6LHDa9mz2AH24D8#1%Sg(bPl}#H8nYNOu6dhvDJ#&y&l1oJcY>0
zr|PDyuk&BE#Dcb6BZK(A=n=FQK==`NTv!nUZ}3(x9|2=Sin*1QgQ+33TbT`gdL{S!Y9v@hI6#25ac<$8NY9)1Rn#R7zL)Z
zC=qi)_+xVA*Gbz{Pa`phhR-J9bEsS@6~NO<-o
zm0$>1*|<3#Bdv*^_n)h5=y13HBYi7wv`OlWDufI#*xs*js*+LB?tp@&!
z(h13^K{76D)IQv9Bf$=3$2XwJ60Ht{?Evv6>!6P=)hFdskVt;j&edli8ey)D%cP%k
z%+}#$MAQ7sagv?C6K&Fhjvmyx%k;JUD0s5;`*Zr1K6pgfTkjE;T^jOgP^^~ee&BRW
z;CxVne2@3#Iz3i|C_;`q_X)a7Yk>3@D29X614%VtAfcNp&sO)t->iuYc-QCw2d4>ygr2Ljq&|SiEg3GScu@NYp{FpP
zk%0cf(x#vnLhg#{XNE-P|E(AM#ws@WTgn!zOlJRJ>E7=?PE(8zZc0tes|@QTXWKAz
zZ+r7Y#i_~JgOqcXkKm`x;^DK8D-yU&v0YGdd9#f0eynipf7wzIQ{>A+08768*jT`<
zzIJsne$jeECT~w4BMlTD&#@Me?0qk*gsgH@{(hXPw4D3XYvswi6Z*{F)r913#)s@A
z__*0#zi><-HGv*66#{25QQBfe-d$(yVH;FGIZe5G(d1lbYI
zIQD}B5yYr=;|L_ut8&t#12{kAe?!;ugghBVo@I&u$l3rPe(RC1Buq3@HLjHn#ba54p$c9K`4z
z^FA7s{EPI0dw2#fQ!*;k7L&J9!gA_LX#GFtx+TSf@y~6pX4z
zOeQ);$HT7ktwur+jB!3@&@EQJh^5ojP!5*#%{obr!BmbzD*ggJwh))a5MCei`kYAB
z;S!PfmhMEt%#I@>YWAHBGKr3(sXT@^q14}
zBtcVIfm9ihA+i!=7lHQK5~iEUeud6ko$z!=XrcigxeL276o?q?Mh)N;6jzU_j~
zxB?I?>Yo4>s)r>M#L79cEjReTeC_{Y8QazFz@KiAL-;UpQMh>c`R!7!<7eOVz^u=|
zI6&?gPG&zNaZ3I|a%KdX;5o#26CiO2U=&vuM3B7_r$F+n0x-Y$`74Wr4~xVFi=}@<
zWaEkz#)=ElVyK>`$1xVnw5BuZCgSHm6tGnW$0WzC%K2-3^w%fMT^TGI$O=b|hqWB&@0@3EnKCKtN_As$@H=x_?*oDO3-U
zaH^tW3~~awehL&Zy=7c>Vv2~(nysu|u~IL4UxJK?8v@-qRpJo9_%*6j&8@I1b)wzj
zJ8WxBRC7GCkfSx2|579EW~>g+XqBG3oN#XQB#cjjbP*;}pDbcrapf8JOgfW%C22(l
zBE4tzKJSKHh8HvKAOGg?sHud
zsRoYf>%C>+<8MrZ+V^BjP|#qL&g~k#`7qQ<)bWvx^r8H`jcNB9m=;6QRLi>gOa!6?
z0pyP5RS4X@*(^a^ueLm;nFSJOnqADN3II6v^HcTnOY{pmmIE-wxBh8RgPxtwxJ*9*
z?O4ux)ih)i1Bw%AGQt3eBd1bzA0uH%P2do|T+_C$bBOwqiP;$VP@ban73+@d;DSC_
zy^HByJyR8;yO0W(v;2uGwExB&=hv8~n_bL#$tk3iEeIP~U>R8WgQQ9l=>FEp^bZ2K
z4H?WR1nyV@X#fBMsZV?jB(RC@s9P#JV_Q5>Yz0C<}dG^3W8v&3wg#GEIR6COCuR
z$$9%pPQNr*!VKl#ku>0tPW#BVaJpQ5FX79y!ZqCchAE_}%`|~!XH8dU1?xPGGbc2Z
zS|PD}(Mwzs(M<%NNuKBy3H>A#nzpo>rN-75n>-J1NaLr*Eh~;mtYvXDED$TF^X3_u
zbx(09Giij4(7~nvlT*b?J$z1_-$(%_i37#DT>y2Pd3iTEiem!#=ldS+#BbKUw@tGDCx9*cc7f9__`o61nXXUl6&X>
z)oph8diD1)(dnv@%{Zs&Bsc4b_{nCX>pJNa|Ie^3>Mo{2`$4sYw1w4GwheXJurYq0
zZ3(2q08iJfkaw@pn{Ax(s4pcHJ_p%J2k&bS@}>?7P7ewx4zc-wH!w&!oI|yCOweb)<{#A?7yyW(
z1Y&?U#z!B0j@pxsI%|)*r;d70kNPN%2SksD43CF>jz^P@$7_$r@_|e+z?<`)s%WIx
zNmy6V$>H)8nKsS!lz-eAFj7=Qxo
zcd^*-q6fc;QNQna(B1XFi7~*c0-*Q|>9paWmI5Gt_?)!vD8%uI;_Dw~{2!)!xAYHg
z=^o!wBX6k+ZhO9-PICcpHNE
zeo<){LrgabH8+X#G31&sh^a9|g$fveBS|nO9Khncu=qceumS%77E2&bHIkT4)HSPq
zbRb$5ZWyXlw5>_)uH(&3(djFXAKh3q3Wo80R>WWdL3
zvCoZA%BmNdtKX#d*}3`BbFQ2CBBsfV^0vn}7Y@y;&8mD#^(>ASYwbUJe$TP+UT$<9
z3YU3LFSOF|{7Zgb)eoWd&R3I%0U?Wmi)8vxE+v$zDj`2P1)2NW(uK=NGLMnyZOH)5
zP^!%Hy|v}5|E6ig;n!)%!jZQT6M*W@k5j5J0em@wtz&xS>LC%8r3)Av!q!jv4ROz#
z(}Z(~mp+}(sE3MZn3w&*i`xM|?$~MN;4Xvgxn2Dnp!+4a(Hnl10<8!w^>BZq<}E^S
zNkF`c&upbHey{Gx;sNsZ^0Mv$;3u;&4s@XJTMZ_+_w5C+B^V?7h^I;71!qJ(aFS4Q
zYhe|bI<4OzShj0ofXd9=Pm`XjShXM`ju8l6WVS7fS)wh9NOuaNnE*vZH9aZfc+XE=
zv@7hH1kshPOp4@FJuFucP_IaC%AnrYwU?N!QKA#NUn
zjaO?LDt>RSAE5p-V`i!^)6(Rp)d|<$T;kuBj{JO~5vKwxdX^O_%*dOe;7_%0^*G?Q
zTH98F(3DP0uFYxDgRE~OoCivkh9&PleBYO1iyV2ybJm7*i7h?m7kjkzi6Hcx|xBc^x1`HE3J_wOg?z5PTwYQ$bDph$Dh-M}VU@
zZ0)sY!QC2KF!4yF4aI!8{sj`!q{q0KSfJMD@>=b@ax((>ugxuRC)v{tX=Q2c80w$V
zUK1FR1Vhf>S@IC*hej5`Pe=74w>@a_*%`r}m5*JuNCI@OzQx1ih_*=|cskS&J@5x(
z6BNANBIyMEb$K$(P5tan+m2>SR
za4GQXw8>K7TWWi4VAbMJ5dh=@Fa<{~W=>6S^O@6=xSi=b}8qf_%FS$d=
zVs(-C!@1Q|)pvb&+FLAN5m<%hxKqa!$XWuxMAVj#Ul;%=X+~
zW)Lh73sObo{oVQ5ajiKd059+R&y)a!3~VzHy%I$1=JyZnp6IiKUOqZr1NQ8)iM{(t
z0=O}^xA%J599SH!rr7PUN!?!+$WevwHfsg4UhxkT#esZKj0&-KU)$e;c9Qi636O%=?m5Pi;8mJ-E
zpn`A|H)dSPNJ($^99T4|T&faqv37X7+qI&a5Mb^{NTLR({N8TJE-)Xb#`mN1?Fwbs
z;ZfXqu9cEOYh6&(4%bf-6a@KSJ4G-}@%jo2z<75tqw9lhty8I$}sHWb}9U@1bm>1PNx<=@0
zh7yytNp)wNZ$gi$Q0u?Oc0OF?dc|dVW&W$R<|rfb4-ioIIHvFDT4TC&G)J@JO5{fV
zs}T*(X|W9C~;S{TJ5y`eJpAwb*oJ-{h_9fYhTu
z)+7%W!%y`qubvpPXbRlTznGLXDvuUQ|Ghq0->AL;eg2x|K3dG24#0o{s`>5^T7E}o
z5?-j2n3||sT5rOeouFJ}n_pXgeeA6unzNbz4fEJehy3u3V#4fJ?;%o2(eqWC|1f#p
zZu&ec690W{9?W~CrB0+Aq{Deu>j=rFx<^y0
zhk(WnhqY5cA~a6MARm;|`=y12p^{oGu{#MqJkDL@0{hYoo%?!cEvKBWtPK+i`j&5t
zrMsU3qcTT-lanFs+m9`S53|7w1LZq1&+`bc=8IQsrp?sr2)bWkLI$IV@_i3g9pUde
z$O(Z)Iexlh5
z(qGDGcBKU2hF|q#Ad;g}0E~k~@RAJcrsoCUZP&P==cONb!A0khm83-|H%_+#OKE8JNUVp6k
zpTlP%$$xs*xu$yMv#+PYk9A^OSTEP$Bwl}|gO83SE3ZaQ`oe*trq{i08oBZ2P8t|y7t+ES=P;
z&22bDS&tX7?$o-J23tkGXwmlU%8;NWRy-B{YUNlVa?kF~CF7&TgPJ|kL>|+d&N8FF
znFzE{?q)W1`i{t1g{DW}wCa5wh@=jr5pQE5tBQnw`t&vyrd0xBS+X8Jbm;v}bRSpE
ztNoe=*9Qf%7G|q&cb7?ohd=|b-j{!Br+{Hl&z?S2B%0}a<-DGBH&u+XQLHP#h(xnvd_}1GGDV2-4Yg%_r3bTblPmjR7Rk?JA1R0
z+$d76v61v3zYJTl(oiGz`r{9?+MbsM`!7mv`UoGGvbm4Pg&pQL&eU3VC{fUgMSerT
z{IUGTb)<|yn4oIC1j~=g`@;O-NMp!f5?;J1#ByJZ*%iX<`j#zAdAc6`97b?&qFEFB
zff0v}S?b=g9gmY8P4RsrCKu%ir
zzJ^GhxUBY=y55SqaZZ}vvRto6*VKLZz)ac*Y2Rgk)59GNWB=r*{LK~45!QYUwa5dd
zyGaxGW}#XmbfkA6YFw0c$&k$iA^UNH!FcobX1HcOu!9=KcpjzcQPr*hN{dtc^n9Cd7bgPW@vT@!P$%NmnKK03_Z!5Y#!{cFg$4nOgfd4OHD&;{
zimx$MSnh?nIE_IP(Q&yZY>5gUnWnzbSa3g7UH_tSkY&X2+i=@Rg{HrH$bz=U8i|~`
zj#x);bhBs~Rzf5=vkEf=-q(3|tAn{?NHwFtz9<6mQcAKR1s5LdZ;kX&-M%0!6(-T5
zz3nZ3xR|fllnVrU(?&&|;No29K->SAm0CBeN|UkQY2icr-6t3)5MGZYj4w~>3eIp|
zA=^{$$*t0Yc$85cp~ZvH9Ja*VI?>d=u{p5tdRma2fO_ssk2EWV9vY_FRe-!sEz_qB
zNl4R+90?m6)&u55<;JZau(DL?H)N4weIJBXkpu~oy4XpIDNe|a^Hl-_xcQkU*9@kP
z4W`#7_?BvwB1X^Du*fky*TaQSvRM>pN->61JW=Q6B>Ws~XPd}M#Q|$X;p0?O@1y7h
z=~>`lm-g<*{v7VkywnJ-XK`pIMy=-_Nj|~U{e2ni2$ZKrZf!LHvJdnj(m&aM%PL#$MgD1ky4y&Q}P5Ny*ZT#+ngGA~XXjt%kb9#J}9ZKa9rX
z{hZkL2U-XEQ-wwgY9J9*xOxnTD1C+~&zQ8vn5@*8I1J1m0}{R;Np3KCIR~TA)umFN
zjlu$%(Spm6_i#qEm}7(qv2sm^SZo#8(ioxzs5dVszvmXoMmt772PuLOG6+(~GExJr
zBVClV_K^1C|KYQe`1~X$5rDm7En#vRAkF~j8~tb>`V6L>i3l(BqP$==3NQ%I_2882
zE4wWj4=Wm1eQh=lNdt`v|3#3JG++?&@j#oVyloR6P5Q)3p2Eb5x2wJ?LC2yN@g5N{(Lqe#yo@BQn@
z?%wJ|W1#u{V+R66sH_XcfuKR*F?rUpHP&&ZOEXsB1e;8b&k26|$?g$xSxUVw0>
zHsEuQDW>x%&lmkX2Op}cP4}wQyh@S%;!j)Hb;4Qp(J%e^E<({Sd~vSO_?moxWaU1N6>5wVFA5=i0#hf&6K}eJ?MTXyiF4!OPn_%?mE
zE`U%C4}j_Zq#F%6AGv{!B13{~#-711JOO{Yzb=%Z1$BsQE+XJWAXyx=j>@q?fLH-=
zM+k@BgT)ZOazvk}ryQwnv3{m!?q{*Sd#$XevZSy8!aHBo$K3~cp?HB9%cL7JpCyN{
zyJIJt?PM?%ZZ4{+8dX$|5~G_J3$S`I8#_T&dNOI$%+I(K`|%t}cQ<5|WU(kN3NO!C
zR?hZ%Bz4+^F*7AQSOTb3$xus_JsqB(my8gl0C0eI*z=-@rG_n}tdT-{SL_ep(Gy5veOEF(e
zphTP$y=wY#BN_M2iEWaTO}Wxc=i=j^k|I^!hY_T0(ex(F9)L((l%z3%n+J;^7Q}-M
zH|LK?`T$B61#4`g??Tfzd}=V|n%TO;&$v6;W?Z~ePr)Wjw5LjBaBgqB_Qej
zm5p+&bBC)g7!{J$ywpRu;!fZmbF$icG6yAhf*Er0%sKCd7dE2}^)0DXK-)=Z`}$}O
zgU_3*F*~>n#eKK+mbsGMDU!CRyWA7F4=f@zdV>MkzEn94V!i62l}U(yO=qBKLyC;B
zVLGTlGh272Q-#ZXDxtGR_xvkax!_Na*UKrFF}!#3w6g~9QtUncEqtBzy_8;|Gy
zPBs-irEFbx5KiJ&rgw9jbNverxgU;X#EjAUQ0%*I(f@G!;I0xtJ4{9d28uT@y#WHT
zFSze)CgqpuBLGY|@x@Z?dt8}{%|yuGxbN=HFd}rgLiwhIRO^qD;3)u1=OqU1_3bqy
z?Yye$3NJxG5L^?k3skmMnz}6^a+;Nh3=QhaE0jq_F-bdz|mXX8Zy|WE2&~
zCo-Y+jAuZcAINt9ksmoY5D7z(z=j9ZIIjs>9}JB*^H}e_&ieK%7luIVXECNMGip-)
zkEOHzYwCZ)@L4iojL{9FLxj|-Q3v`O(7`j|8w7WwlYotu7fENg-y0-F9Q
z(#;h1-xqwOo=9A*X`;tkG$(5e=NgC`1AXRk{>b$BU7yTSfih7v0+fUp7EZZci}D8xD&?tAkiLj#duA5Z4bp82hpZ1m}Y>tkHe%4iHaGn!1VAh39E
zXL@EczKv>8qHSVY3lW2rl!v2h4hEYw61AIf*
zD{YKQ;6);ldM`i;|H(WJ72YB5HVf58aVsJrs&k05fOc`Z^dwbVR0mx
zq2_aGi4w)H5)GlR@2YN8m^9v#+nZ~;GxRXB6qJj)f#pnUj8ZuG)Q5*WQqsWFG3C#L
zzw-C`-(qv?Ttzx1r%ZcOEXK4PI}gDNzYUHDCI=01pg7iE=Fq|4Bs>-(GYLehI9DVS
zu3gU<_5^RilZF2Ny`bP!2uJEqYlQchg6Q=v4+n9YoU_!i`mUH^UFL+WVR>*46G|hjw9`nVy%hCU3ra76)->$U_CPF>#zuaScO>(vuAu;`vlF
z6Q|}-90>5b_IdOk2bCOH*?pLSCsV%;EEqS4|#K0v&;Fwg{ERpe*1*DKhmX*O?3PBMU%Tw%L=|!;s
z{1NQgEa5Gg=A6dn=j+lURW6m@R~F4@?o<+HTPj%PZ2+AxeI4~&T)MYOeD~_mMZv@+KlXu;0kB}{ayEJ-V{@EQaI&=OXPbgo
zN@{2Hg_hb`GU=kmSdgTSkhJpz{$-)@wHm3C4F{SsWW0z@y3CW^+*eR@bYgyGIoC?&
zD-f7Y56E5TDgzUg%OQaKp<_m+5)P?P&gGVzy>t#^W7vDvVUlRm>_@H`C>ek{J-K?h
zZHg1Vis0n(48+02rnyvi1`;ewDHiW((4)gOUq3k%$cWXDxbaR{9*Pg4y@gIkd)N+%
zfkLR|%MoSAUih`*oXu5Eq5gp6`C_(_L4dzgeT%`x$0{z|p%N
z4myh}o2AGP*sPTMk_|ZOoVxE{*Z#}RBm
z4E8Ua!_!)%a(@jMtsJ-qfX_{FDzg;8PZ}-I5G!2Lb`a?{jbHb;yIp$Wlaiwlge(
z_6BG`-9&_rtMqj+$Jh8xb#3}D
zVgD#N-7&{yj`d6e-TVzY4d1dqv2vg;aTr=W=Q-f=xCA{VbNz~J4pCXDIO7P3*Gm5U
z%`}#HI!B@6j@s2;WgE^~?kdR+gipO-E?gvZw@Sqp7-V_gW}xQz;IuEVY22YDZn}B1u%1-&14S
zqg~X=kc@I^aHm9Iqc-v|Ox0ZbS^c<@!#rQCA|B%e_(5G
z(k6t}k21sWuY9{5K1EhLj(yy{4m$|%3i)^NnC0&#$F+#J)c?3CBCfnP2n9Ku@?LJM
z)$j-52N$0pK^&g1=e>V8Zr-O;0pE9K|22Uph+@tR(C*bd{3;BG}rjIA^`L{*#
zC`YY+{G0H=pFj6FJ@3}UoUWZF$gKXd)asC=ZM&7^(L?@wolK+oA4)!s+cF$84ZNTL
z-_={tpBC`rYK?dopbhkr>EbHf3OuqH74Q)S23*=;0=mDfK>TJ>ydvr}`4T3O!&3>R
zr?arCb)102GIMZ<3CU#Ty$tECp7&!n%#+xZ=H@C
zseTIL&2sd`aD2OI2z8|@Ferl!M{{&OnueL9Ch3a5S@B|r)UaAiP}{)MJ5Q|ePv}ga
zgmtWcj2H{UpanimDWFYzytq~zS$n0}wFrzFjN_uo)MAmQ-tn(Dv8dEbXuPyDzagy*
zYsoiRi=l>B-%c|Gt@#9tP(uFYLMG)drx^!~R>)}Mox|6nZ78w646zr^VqF_zea=?~
zH^i&n94eOaH^FJhjwElSmI@BPbg}T^_>lC#Yw30`tx=C*!~9J?K}I$-tHATId&DsX
z$6HY%=#LuHAKh4?%IpR~^Mw1Rin`hzr^VV>6YsC|5_Ox(@+p+o#&WQc0l7j|F($Q*
zOtt*UA&n2$MM}mNY-5XyAUq#E^cIk;+2{?4(`CX+*!6{dWM_#-0*bVZ%;(sjEQviqOp98*F$>TW=sdLh+Lld31tV8y3`QIWY)vv
zE%jQ+`z%D~+3I`V&oR8{M(li;Dl?}$7q@&gB$%J)-@1F&yH!>woDVQ9f6`yJX_xZZ
zvrQKby^NQ!cu%0~pB1V9bIGuB3#PGowBU$)SRw-&!F{e`!GCk#Ij+JMA_F8ocn}!8
z`i4~zIAsx!U@BaQvPVeOP>A7|P;-yF?+Cs+z$Iw2E{=P-_ZHODY1s)9!41f019Yam
zB~C;4yoKq~s-wzae-QrpJ^5B!O%;A@7e{;ezE{pa%rH3AopQ~@PdBlkA
z7_oBtkVijT;gjvWg{+2|3In7bdzy-j(B#E8RatzUqrJP6=)E(1S45$6{O(l|6~lF}
z2G5kPozx5qU~)d;JFEYKU4z_*5hW`>KNQ+&*$nhy>?>>B_svndS|6c8t8W!OB+s0t
zXX>G`>bTlm-CD4IZJyoN2(Q|FXVJ&^ydJxI72K|M=)@<;r)ePzM2nt!6?tnR)3jh|
zL&c+_B@fo-4tKC${t2+3`G1`P<==x$ff*=2_9GChdTDfc!PBh|g|t{1~8ba*#R>^8jf
zt{>FBOWweHH|_2=QIY%)cbk=~<$(H7p_(-2JZU$vK^?11wO1p#IP-DH%O>1QX5eKx
zjD8<-^B8I_5O0PVv0KwJpEh`E>|=hpAv+pY?|@u)z4Fpf7yiLlX&IAY*(STa3qi5tCDKu~D_igQWh)8kf1TJz;3N>&}~$%Z@k
z<5khRtwpd``pJ(Q2(Jel3}$hZNv{M9w__KlYl3~NrN5Hwu2Oc14N3bB1p9q#+8uWH
zoyXf-e;G;fTTu6Seos6j$Sj`9EB?sVdVaibSl^XsGI2z0B|F0W1U9-h{CbXHzd!8|
zrvvC~0G0dhm)T1K;gzl~9QZaEIx>F#`jZfH&9FRsV`umWYfj{w5BJF55q$d*GrMys
z{$HEwzCM-sm?AM>)VPrCx0ml1Blfsy9fj8nn+ewV#;p%R%mR-HIJ5>l{_wSBM0^Ie
zu`Q+HeV;x}#4CEcQ8y^<50fTmZ1P*{W*6H8N>aQ-Qo}b!gSEECtSX_PAD#_Xjh@zo
zkYF04%7Bn2O^D)`yBR|vLdC|D2Y36RAOz{W4f;n}IJqGP$aFoH^>{&vHJWVZ#sdT}
zf`Eh)FS_DFo|gI45CAj~HY~R5TstJ>OQGTmul`=g?K|{BVn5;AUQysE^OYvEXWs7q
zwR3UlldxACacQcP>+BM*ijvJR(M76A^OATo*1cN-2DXR$TM}f6Oz89Fr^(L7KJYl8
zZ$pcg`p5Ns*kezzYUx6T
zDN>t0-U}QGKAIE5QC0_zln08~Hw4wOS8~?|zN$(;8n!gmr^JqS=Htb!bCZjP5wBAA
zKQoTd{pa4l4@=jd`6VQ=jQY0ckWeU+kkO!Hikry}6;BQQA#<=Jaz1<}WN@BY5%6k8*$LUpRVLFB>
zKLm7i>$gPav1V4K4v3Jn{wDNhN&NUB)L~vcTi)Tic1yCl1KxK7;swXDw`g-LMe}yY
zk^jBbR`4*I58@Cm*6AKrf?P71NUB6h@;O`pf`b_YzqaD&DsYMY8`$<0F(2C{^3DbG~L;gMR(O2GAq(MF6
zg`i4>kBI0Ddq(58}d*u7M
zW?bsM-+F8Y^40Q$&S6!?vB^l=M
zmhQsr!)`C#4IqgEFMlu~PhE#nV*7vcs3`LDC~9fF01xT9*bw1ca-c~q7$6(puFY{r
zQSH&Mkn^DU>Y!$6EY0|-KtRYH1>nE(u!b;lsBmIa7XO)`PiW4^Hov`H5o!{%J_Kre
zmWR)Y4Itx?rN_uWKtSvn?IbYTL}XD44_q{|em`A!vNqjKp$~L)>u9}T299~+w
z_F;YQ026*>d;&%#G?HO_a5FbP@{6pMxMaV>_
zJM1+D)!;
zW$ajjYJCfQnxr@m{1K8jTE16HO(^{u0ede8KH2qnjf33@tgHTMTi@mFd+6QbEhOoy
z8*-G*bC#nZ{62v|S))Q<6V+9W>v~Kk00Lk>0kG&~x5#vNFF&|XShJ~|D7S^z%+mst
zkoN~@Rh3>s9#g0eF#I9;oC(qRR6J~mlPDCcKpvRViP5Jm>rOrrFzY9xhX1@4cFz%G
zpM0fvX*i$Ucg>j)XE^&jTl3VIm7=Zf%UyvR$B7)$u|vb!?b?sVpbo3|we}(caKV4S
z2PE=f1t79CrvZ&V5dth&EtMB|XO4*IdIHrj4we>l9-Q8K5b<|02zb1+Zu|xfjFEJ@KA|JSbIFg4fL%i5_%pDu*!lr
zRUU3$>+9ca3xW3x-09rr|3ix)tLEEB<_AO$H@~dEx&2w9Ug|^nSse;*T;YsPD4*!h
z7(FzS{5U)|WU|)Rx7YLV+q~yuO0!(+x1;;IG3K&Hs$Ve6ids46Mk1$V{c1JZv&$#;
z$G!I)KBkoV%jL%J+bW973LXt7chv%9i2b@B_PX3y0%tcR?Rcb(dSn{nI;eU=V5bMT
z*avm1f7lbld?)L6tiL4ZK~9K`dT#l{GVVNH27RW~MF*Z2D9)7IpPrZplj?aIpWY
zRySQ_A)B9d>pdnP>qh(L4f4=qryB{)PCw!WshJyZKKC4Zas3MZx9L&hEh07erA~W$|B|bdh78hk4`jw
z>nE8Vll|Geww&L8@hWjV_O37F@#>+@J^o{JQ-tB>ZIa{C`x{qI|JgVHR;i!zWxGZO
zT+$kwPg~w%PoO0MeE8_CtNWR$TU=bCHOhtp0etT@#}FsyU)W#3DKwd4o6*;Nk_HH
z71`NUT(z=CnXf;Ldrvp?d_MA#k`lFlBs2LbySZ;r=+BX)B8;I$rc?3fBNLgKH0&GD
zH;03_JzWI{EfO?pj5FFyw?eg<-Ab>}F+c<31aoaC
zv^%Bf2Y!sF;oIg7CZ5(U`@j13qWGQ2Zg!EAk?w;=?|$VO2Wn|G4u=*TG||db2FC);
zCCUGEd4I$0N^bpiuNIi4y_?{E07>m3*W=~jDK!OIRzWyV_3TErMn)%Vx5=B(`o2A&kZKDI92L;_XG1j?3FG?n|Nq5SeS0Q)n8qhe^i@ZIM}hW
z{76IYSLFqMi)o9p%;j&v^~_5soM_oWJGGvV>F+9?`u$NZJef1N{&tB&Y3%%i(6Xmy
z_dP!`$|+=FD%}R#$L?R-I9biJl(za6UF~f};HeUznp=#1XHsKVwtQ>-X>g(95$a2u
z`~r+&tgVTDE329?o*%9!u}y9J3Hsc)fIGhVxasK`p1z8Fn;ZQZjE`?6@%*_G{`(as
zZu|9^-XVQo*VD*I>-mPq;NjKRe<`U?Z%2LSPo>Nk?z=rtD@psp;`TeC7rjv07`oij
z&b4Q>4?;I%zyp{xc2hoDe_}8jr#^*F4SHro+e=mYR*f!`KyCVfr6qsC2k2p)t*Eb0
zC%a)@AHGU!_vH{f!>sB3ni=hyHs?C*8PtyE^6PB;?&;#kg(iZVmu*-Jw}>7zh~T&x@L?99way>!$f#=
zKI-d@AG%#-j7O>~6@hx=*Q6j<0s7y8xP$1m~1DK2yUDR$Ukr8|^Pr
z${|fm0Fr76!VOk%kH(U8&DaVw_M62B9aFHw4m}}DGoiVnOfFPEV+kY(k48`2-Ed4-
z6yGOWN>|@_NVND_;uj>_IM?=hvzMN*mL?RK$Skuq_Q*erV7CurSj9)^N*&Sgoby+>
z?t8}kF$hYfpaFEv0B|JZQATjX7Z<3D9$7f$86a}%q4vW`uMmEC@0aDquQvrF;Bm>T
zavvTQ?h7dpZJB%elIukB>gY_e<@hm0mxA3ogTlb0Is-qFt|w5QHW}>PR5m~X#if~>
z-<2yDcqaPA2m&DH@x5$xW{+=&YS4JPa{dfFP=sg4G;aV6j#dC3Mwkp;ZqH*IfL{4Z
z#m<@K?{&Ti$u$3%Wb9z!xF~R4*Lgal>?K63GjkN_PJ|(bF(|rX&|K+@c*RK)`?XWh
zqw1k8!JMD3IxGw$tbR&$b~fCgJ!+uODji1dSVW3MAUT@xHekVgQU}*JVTSb()0YL7
z+#gam$T&iQ$hl1C!^#?Z%JY831M+s+k!`9+|NczkdFQ>+)(Qg+!i@4`vx)=Pg+tkk
zs~20j6NP<-Hy(%qDxTRn;EreujRh|iqJnnOEaAZy71YO5n;NP)S4bQcP_FqQhy6!@
zg^P4F7(&9=iWQJVe)-fShHegkPYKDcnOTe?gvZ^k?o<)U5aUY6#;{UI;*%8`^a!Bv
zW;W?vm;imqV=c=J*6iJL_W2`iJ%ick6j^XtF3)VlxYnC@y-Q9m)vmQ%MsVkTA93#c
z0Zz}qO&@!KGpmR0o?JUu3JKM)-vJ7kr5ugFabM;?I~14+sqwc(IR2V1&C4H5Zu&e8
z4A@g+K$}j6)P9TmF0LzGq?$$s5nawq*!#C8emuZRa(eLQ=66f^uNyQQ+!Wp@qR{)b
zL<&)^<0wrpjCj}2R70>(7`y|a=$>o;Cuy#sZ3{
zC6gQJC^r`kDLWus_BQ@!4w)h()t2pB@Ti^K(%*k&%2^cra&<*hyCTlJao+O)VIRQl
zO=s{u^yAj0)Gh@86!AR**aHathJJD}jWt3z&^&5hHyOO1G4R=thuaiDmvcN!!Ly1_
zqW4XB%NtS082Cn0HX~qmz(I{|m^w?rFZ=(1~TPaf~*xk;(n_I#aK6P5NcaEIuoF9KW
zu`jVBoVMnfS?BTaGhXD){$xc_KuS?!yLoVc`O%+o0f_mVEP+j-%{0PvbB09L+e)Cq
z+p&D3!DXBb-mnz1CBb;Geta^1`~_4Hc}?x&d`o}GXQqn|iw)1$)mxV}qWKo#&S(tY7(`s-(EBQHT{+wV)>|Cl
zA!$jmyyt;BvMB@7{1(#uA@tv+WPQbb!kneNMubaTOH^fiN-9OX#|)g;L|bG0KM7=;
z!*3pyt8)*PIWkDAdrJ)ReZf?)gi6cvR*3S)$~(O;dzho}%}en@^vkL9rt42B_dR*M
zg~Ettx#@!s(cfZaj+^e+gbGG
zdogU)yXCK0CRMh>nrgEyl1Vi3`;@J;+_i1xSS|3-&p(3_|)
z?m(toyGim@o(XjzdY&
z5>Z3ycz)_%AyQ+XrT&IUKOT_QfP}MG8B8)JD!;cL_Ii;KV-u4rltGVmXLJxV*W_&C
zvq;dw%NS`5Ju|tOmA?tUtc5XU=_ET++aaOaR=K(}JDr~l?D_;H`0}o<&6-R8lHCb`
zef#9dU0{GQCs;V485q|oQJOq8H1KO5Q1G$?<-Ga^lEp1;gjTdsckZ=|5C}%bMg_om
zB*}6M*)$DVb28dSd4!KcY9v0;LPxG1K_c$2umUUu1wGebI)&nlSLcG%9AFhqa
z;(q)v@E5k_5_%CR=;JwNeEs06WFF0aU=Su*PAZgkS68py%~j;XwcTll51(z3E;j`6
zR&slRI<>#}vZT9((sA>px9*Uc-M#n}KHYWq`OUi{v-~1djO2Ca8Sl71ld))saVOtz
zR9M*TOJm_ZpEm}-WpQXds?fd7S(-iv4{pG3-jiz~ux)=B?~?
zz4wm4q?}^Gnpu-xOTWM-S*}tqtGeR-P}M$M#q2rqy{O@M~)2H5E^!w_)t~CWL_rsRNmd6&sFb(t~4{hy$rzQ{PBSl
zQ^01Jzl@&0$53nn+-PrCy}8ml@5CA;?+CNGA{|o_Ea{7~dEx!cmgb7l+%B9V>{ekJ
zf~wlPP*86*;l`o6pZvU>u(iMRJf81)o4ufDwuH5uRleO}g^rXWBxUWg!+7YZJ+<>I4>I>v>0+iefk5^s+Og%1p|)ZCQ1xGNp4Xyc_6>=!A9
zu*qSnvc|9&TuOEf@@ay^>ZZX*{#MNUqDJ@>=$K`M#
zjZ%uD%e+HYyba=UUCI5Ou;77`w~rGgnJaS
zWi?qE46>lw98hi60DUHiEk&cQx{EbUqpp#?zIcGOXyEdni#}z5zTuvn2%+KiV#8bZ
z#`kuOAJ0`?T|?Xz!@2Ozx1X|Q(((QH&Q|r4y~>HAvYp`30s&h_m;7Qc^H?N4Dg@En
zKW8a^&aw2IhvUVJ7F`vIN+gOZNrS%1k!r(;$>{69IX~h
z^ma?Fcb4d_`8nK++kBSV0yx@3?Aw>v@k;s%!Lbz~EQo7G#8eLa6PlkTjqC7x`@hQv
zJIv0B6&E?Y#a;DFT})*AnrKG~f+H2d5e<*#>f=BPIQ8Uc(CaU~yspxEW2v>*?y{Ox
z-@91vVlSr+uc8M19dtL^Yz6NY=}K&qUIocV4C#ciHvh*l_~;@t
z_2L=7LzkpOE|WbTNgp+&QUX%t9KPl-tW|QUTY5gD)h!%VBNNp^;Y8IJMMc7m=J0ZF
zM8DKi>Ak_hHqX(}-_=@gCs*Lqmd?weU5ZFr9?$wSo_haPPRXl0&WZmVCUi<0BP(>N
zN(w1kNFlboX+jD~DuX9Q34^MW3s$gw97NG->ivE0X$J`Y-Jhu$hd1l@->fXZ`O5ir
zPj%`SFtlJb+{`fz(zu0;yGOx|qwBDz3v;Amyv15Y7?I&XIy;~?K*($jl)q}P6Gz{A
zl-!{T$M=i(YFx7?DzjP-W_3ujW`Ae(p0JT8hnl>?6c~G6f4%v1udR@~WHPn5IplBW
z!d>w38YK~jpHF-;pSm*th-)FIcmBGJYz={mdu^fOFGtCP#oE%vCtOP{D+{k2m%5)&
zb^KlG#5^==zL
zO59poD6YMs!d6w*Y6F>Vi5|~d?rSMyW$hd1QQzR=X2WA{Z|D#