Continuously monitor your AWS attack surface and evaluate services for configurations that can lead to degradation of confidentiality, integrity or availability. All results can be exported to Security Hub, JSON, CSV, Databases, and more for further aggregation and analysis.

Up here in space
I'm looking down on you
My lasers trace
Everything you do
_{Judas Priest, 1982}

• Synopsis
• Description
• Solution Architecture
• Running locally
  • Attack Surface Monitoring Only
  • ElectricEye and Custom Outputs
• Setting Up on Fargate
  • Solution Architecture for Fargate
  • Build and push the Docker image
  • (OPTIONAL) Setup Shodan.io API Key
  • (OPTIONAL) Setup DisruptOps Client Id and API Key
  • Setup baseline infrastructure via Terraform
  • Setup baseline infrastructure via AWS CloudFormation
  • Manually execute the ElectricEye ECS Task
• Supported Services and Checks
• Add-on Modules
  • ElectricEye-Response
  • ElectricEye-ChatOps
  • ElectricEye-Pagerduty-Integration
  • ElectricEye-Reports
• Known Issues & Limitiations
• FAQ
• Contributing
• Developing new Checks
• Auditor testing
• License

• 🔥 🔥 500+ security & AWS best practice detections including services not covered by Security Hub/Config (MemoryDB, Cognito, DocDB, Amazon Managed Blockchain, etc.), all findings are aligned to NIST CSF, NIST 800-53, AICPA's TSCs, ISO 27001:2013 and MITRE ATT&CK Techniques.

• 💢 💢 Provides basic Attack Surface Management (ASM) capabilities, checking for more than 20 highly dangerous services running on publicly reachable assets that adversaries can potentially exploit.

• 👏 👏 Supports every AWS Region and Partition: Commercial (aws), AWS GovCloud (aws-gov), AWS China (aws-cn), 👥 AWS Secret (aws-iso-b) 👥 and 👥 AWS Top Secret (aws-iso) 👥.

• 📡 📡 Built with full AWS Security Hub support in mind, can optionally output to MongoDB, PostgreSQL, JSON or CSV. Can run as a CLI tool, in Fargate, as a standalone Container, or anywhere else you can run Python (K8s, Batch, CodeBuild, EC2, etc.)

• 🤘 🤘 Multiple add-ons enable automated remediation, ChatOps, and other integrations with third-party tools such as DisruptOps (a FireMon company), PagerDuty, Slack, ServiceNow Incident Management, Atlassian Jira, Azure DevOps Boards, Shodan and Microsoft Teams

ElectricEye is a Python-native CLI framework that controls individual Python scripts (affectionately called Auditors) which align to a specific AWS service or resource (such as an EC2 Security Group, or Systems Manager Managed Instance) that contain one or more Checks. Checks (continuously) monitor your AWS attack surface and evaluate services for configurations that can lead to degradation of confidentiality, integrity or availability. By default, the output of these checks are formatted using the AWS Security Finding Format (ASFF) and sent to AWS Security Hub but can be sent to many other locations.

As of 30 MARCH 2022 ElectricEye now supports Attack Surface Management (ASM) capabilities, showing you potentially dangerous and exploitable services running on publicly reachable assets such as EC2 Instances and Amazon Elastic Load Balancing (ELB) Application Load Balancers (ALB).

ElectricEye is extensible, however, and can output to JSON, CSV, PostgreSQL, MongoDB/AWS DocumentDB, and other locations and formats. All Checks within ElectricEye are also mapped against popular security framework controls such as the AICPA's Trust Service Criteria (TSCs), NIST 800-53 Rev 5, the NIST Cyber Security Framework (CSF), ISO/IEC 27001:2013 and the ASM Checks are mapped to MITRE ATT&CK Techniques.

Additionally, ElectricEye comes with several add-on modules to extend the core model which provides dozens of detection-based controls. ElectricEye-Response provides a multi-account response and remediation platform (also known as SOAR), ElectricEye-ChatOps integrates with Slack/Pagerduty/Microsoft Teams, and ElectricEye-Reports integrates with QuickSight. All add-ons are supported by both CloudFormation and Terraform and can also be used independently of the core module itself.

Numerous personas can make effective usage of ElectricEye such as: Security Operations (SecOps), DevOps, DevSecOps, IT Audit, Governance/Risk/Compliance (GRC) Analysts, Enterprise Architects, Security Architects, Cloud Center of Excellence (CCOE) members, Software Development Engineers (SDEs) using Cloud-native services, Red Teamers, Purple Teamers, and Security Engineering. That said, ElectricEye can also serve as an important assurance tool or educational tool for nearly any persona who works with or is learning the AWS Cloud.

Note: If you would like to use the "classic" version of ElectricEye it is available in this branch, however, it will not include any new auditors for services such as QLDB, RAM, etc. Some screenshots may not work correctly due to the linking, sorry about that.

Note:: If you are working on another project whether open-source or commercial and want to include parts of ElectricEye (or the full thing) in your product / project, please contact me and at least give me credit. At the very least I can help you integrate and I'd appreciate any cool features you add being partially added back upstream!

Note: This high level architecture shows potential places to run ElectricEye, as of V2.0 ElectricEye now uses a controller CLI mechanism that does not rely on running in Fargate (though you can still do that). Theoretically you should be able to run ElectricEye anywhere you have at least Python 3.6 installed with access to required AWS credentials and Python dependencies.

• You run ElectricEye anywhere you have AWS Credentials and the required IAM Permissions - this can be on a Raspberry Pi, a Google Compute Engine instance, on AWS EKS or Amazon EC2.

• ElectricEye will evaluate all resources in scope using Auditors and write the findings to a local cache

• If supplied, ElectricEye will evaluate specific internet-facing AWS services against indexed results on Shodan.io as additional enrichment.

• ElectricEye will report all findings to AWS Security Hub, if configured ElectricEye can also output to CSV and JSON files or to a PostgreSQL Database (hosted on AWS RDS, or otherwise). Finally (and optionally) you can report findings to the DisruptOps platform which also has its own integration with Security Hub.

• Using add-ons and native AWS Security Hub integrations, you can extend your findings into other workflows using tools such as Azure DevOps Boards, Slack, PagerDuty, Teams, or otherwise.

NOTE: While this section is titled "Running Locally" - you can use the following setup to run anywhere you can run Python such as EKS, Kubernetes, a self-managed Docker Container, AWS CloudShell, etc. The usage of venv for those utilities is optional, but strongly recommended.

1. Navigate to the IAM console and click on Policies under Access management. Select Create policy and under the JSON tab, copy and paste the contents Instance Profile IAM Policy. Click Review policy, create a name, and then click Create policy.

2. Have Python 3 and Pip(3) installed and setup virtualenv

pip3 install virtualenv --user
virtualenv .venv

3. This will create a virtualenv directory called .venv which needs to be activated

#For macOS and Linux
. .venv/bin/activate

#For Windows
.venv\scripts\activate

4. Install all dependencies

pip3 install -r requirements.txt

NOTE: If using AWS CloudShell you will need to use pip3 with --user:

pip3 install --user -r requirements.txt

5. Run the controller

python3 eeauditor/controller.py

Add the --help option for info on running individual checks and auditors and different outputs options. For instance, if you wanted to specify a specific Auditor use the following command to run it, specifiy the name of the Auditor without the .py ending.

python3 eeauditor/controller.py -a AWS_IAM_Auditor

You can get a full name of the auditors (as well as their checks within comments by using the following command).

python3 eeauditor/controller.py --list-checks

If you only wanted to run Attack Surface Monitoring checks use the following command which show an example of outputting the ASM checks into a JSON file for consumption into SIEM or BI tools.

python3 eeauditor/controller.py -a ElectricEye_AttackSurface_Auditor -o json_normalized --output-file ElectricASM

While running on AWS Fargate and creating the infrastructure with CloudFormation or Terraform gives you the benefits of encapsulating environment variables you need, you may need to do configurations of your own different outputs. Using these different outputs like PostgreSQL, JSON, or CSV is great for any downstream use cases such as SIEM-ingestion, external tool reporting, business intelligence, machine learning, or loading a graph. Outputs are subject to change by release and will be updated here.

To list all currently available outputs: python3 eeauditor/controller.py --list-options, it will return a list of valid output locations such as ['postgres', 'sechub', 'json', 'csv', 'json_normalized', 'dops'], by default findings go to AWS Security Hub (sechub).

Some considerations...

• To output to JSON, add the following arguments to your call to controller.py: -o json --output-file electriceye-findings (Note: .json will be automatically appended)

  • Normalized / flatteneded JSON can output instead using -o json_normalized. This is better suited for sending findings to BI tools as the structure eliminates all nested lists and dicts.

• To output to CSV, add the following arguments to your call to controller.py: -o csv --output-file electriceye-findings (Note: .csv will be automatically appended)

• To output to a PostgreSQL database, add the following arguement to your call to controller.py: -o postgres. You will also need to ensure that your IP Address (or AWS Security Group ID, if using Amazon RDS/Aurora) is allowed to communicate with your database. Plaintext passwords are frowned upon, so create an AWS Systems Manager Parameter Store secure parameter with the below command.

aws ssm put-parameter \
    --name $PLACEHOLDER \
    --description 'PostgreSQL Database Password' \
    --type SecureString --value $PLACEHOLDER

• To configure your ENV to have the proper outputs for PostgreSQL (provided youre on a Linux system) use the below EXPORT commands and switch any value that says $PLACEHOLDER, but keep the double quotes (").

export POSTGRES_USERNAME="$PLACEHOLDER"
export ELECTRICEYE_POSTGRESQL_DB_NAME="$PLACEHOLDER"
export POSTGRES_DB_ENDPOINT="$PLACEHOLDER"
export POSTGRES_DB_PORT="$PLACEHOLDER"
export POSTGRES_PASSWORD_SSM_PARAM_NAME="$PLACEHOLDER"

• To output to the DisruptOps Platform , add the following arguement to your call to controller.py: -o dops. You will need to create two AWS Systems Manager Parameter Store secure parameters for your API Key and Client ID within the DisruptOps platform, as shown below. Only change the --value entry for either, the names can stay the same.

aws ssm put-parameter \
    --name dops-client-id \
    --description 'DisruptOps client id' \
    --type SecureString \
    --value <CLIENT-ID-HERE>

aws ssm put-parameter \
    --name dops-api-key \
    --description 'DisruptOps api key' \
    --type SecureString \
    --value <API-KEY-HERE>

• To configure your ENV to have the proper outputs for DisruptOps (provided youre on a Linux system) use the below EXPORT commands.

export DOPS_CLIENT_ID_PARAM="dops-client-id"
export DOPS_API_KEY_PARAM="dops-api-key"

• To output to a AWS DocumentDB database, add the following arguement to your call to controller.py: -o docdb. You will also need to ensure that your DocDB security group allows you to communicate with your database. Plaintext passwords are frowned upon, so create an AWS Systems Manager Parameter Store secure parameter with the below command, switch any value that says $PLACEHOLDER, but keep the double quotes (")..

aws ssm put-parameter \
    --name $PLACEHOLDER \
    --description 'AWS DocDB Database Password' \
    --type SecureString --value $PLACEHOLDER

• To configure your ENV to have the proper outputs for AWS DocumentDB use the below EXPORT commands and switch any value that says $PLACEHOLDER, but keep the double quotes (").

export MONGODB_USERNAME="$PLACEHOLDER"
export MONGODB_HOSTNAME="$PLACEHOLDER"
export MONGODB_PASSWORD_PARAMETER="$PLACEHOLDER"

• If you will be using Shodan.io to gain information about your public facing assets, retrieve your API key from your account here, and then create an AWS Systems Manager Parameter Store secure parameter with the below command. Only change the --value entry for either, the name can stay the same.

aws ssm put-parameter \
    --name electriceye-shodan-api-key \
    --description 'Shodan.io API Key' \
    --type SecureString \
    --value <API-KEY-HERE>

• To configure your ENV to have the proper values for Shodan (provided youre on a Linux system) use the below EXPORT commands.

export SHODAN_API_KEY_PARAM="electriceye-shodan-api-key"

This "old" architecture diagram represents what is deployed by CloudFormation and Terraform to use ElectricEye on Fargate with EventBridge Scheduled Rules. You can opt to use the CLI directly instead of this pattern.

1. A time-based CloudWatch Event runs ElectricEye every 12 hours (default value).

2. The ElectricEye Task will pull the Docker image from Elastic Container Registry (ECR).

3. Systems Manager Parameter Store passes the bucket name from which Auditors are downloaded. Optionally, ElectricEye will retrieve you API key(s) for DisruptOps and Shodan, if those integrations are configured.

4. The ElectricEye task will execute all Auditors to scan your AWS infrastructure and deliver both passed and failed findings to Security Hub. Note: ElectricEye will query the Shodan APIs to see if there is a match against select internet-facing AWS resources if configured.

5. If configured, ElectricEye will send findings to DisruptOps. DisruptOps is also integrated with Security Hub and can optionally enforce guardrails and orchestrate security automation from within the platform.

Refer to the Supported Services and Checks section for an up-to-date list of supported services and checks performed by the Auditors.

These steps are split across their relevant sections. All CLI commands are executed from an Ubuntu 18.04LTS Cloud9 IDE, modify them to fit your OS.

Note 1: If you do use Cloud9, navigate to Settings (represented by a Gear icon) > AWS Settings and unmark the selection for AWS managed temporary credentials (move the toggle to your left-hand side) as shown below. If you do not, you instance profile will not apply properly.

Note 2: Ensure AWS Security Hub is enabled in the region you are attempting to run ElectricEye

Note 3: If you have never used ECS before you'll likely run into a problem with the service-linked role (SLR), or lack thereof, and you should follow the instructions here to have it created first

Note: You must have permissions to push images to ECR before performing this step. These permissions are not included in the instance profile example.

1. Update your machine and clone this repository

sudo apt update && sudo apt upgrade -y
sudo apt install -y unzip awscli docker.ce python3 python3-pip
pip3 install --upgrade pip
pip3 install --upgrade awscli
pip3 install --upgrade boto3
git clone https://github.com/jonrau1/ElectricEye.git

2. Create an ECR Repository with the AWS CLI

aws ecr create-repository \
    --repository-name electriceye \
    --image-scanning-configuration scanOnPush=true

3. Build and push the ElectricEye Docker image. Be sure to replace the values for your region, Account ID and name of the ECR repository

Note: If you are in GovCloud these commands are likely very different, please review for consistency (and open a PR if there is a better option for GovCloud)

cd ElectricEye
aws ecr get-login-password --region $AWS_REGION | sudo docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com

Note: If you are using AWS CLI v1 use the following in place of the line above

sudo $(aws ecr get-login --no-include-email --region $AWS_REGION)

sudo docker build -t electriceye .
sudo docker tag electriceye:v1 $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/electriceye:v1
sudo docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/electriceye:v1

4. Navigate to the ECR console and copy the URI of your Docker image. It will be in the format of $AWS_ACCOUNT_ID.dkr.ecr.<AWS_REGION.amazonaws.com/ElectricEye:latest. Save this as you will need it when configuring Terraform or CloudFormation.

This is an optional step to setup a Shodan.io API key to determine if your internet-facing resources have been indexed. This is not an exact science as a lot of abstracted services (ES, RDS, ELB) share IP space with other resources and AWS addresses (non-EIP / BYOIP) are always change (such as when you have an EC2 instance shutoff for a prolonged period of time). You may end up having indexed resources that were indexed when someone else was using the IP space, you should still review it either way just to make sure.

1. Create a Shodan account and retrieve your Shodan.io API Key from here.

2. Create a Systems Manager Parameter Store SecureString parameter for this API key:

aws ssm put-parameter \
    --name electriceye-shodan-api-key \
    --description 'Shodan.io API Key' \
    --type SecureString \
    --value <API-KEY-HERE>

In both the Terraform config files and CloudFormation templates the value for this key is prepopulated with the value placeholder, overwrite them with this parameter you just created to be able to use the Shodan checks.

This is an optional step to setup for sending findings to DisruptOps.

1. Create a Systems Manager Parameter Store SecureString parameter for the client id:

aws ssm put-parameter \
    --name dops-client-id \
    --description 'DisruptOps client id' \
    --type SecureString \
    --value <CLIENT-ID-HERE>

2. Create a Systems Manager Parameter Store SecureString parameter for this API key:

aws ssm put-parameter \
    --name dops-api-key \
    --description 'DisruptOps api key' \
    --type SecureString \
    --value <API-KEY-HERE>

In both the Terraform config files and CloudFormation templates the value for this key is prepopulated with the value placeholder, overwrite them with this parameter you just created to be able to use DisruptOps.

Before starting attach this IAM policy to your Instance Profile (if you are using Cloud9 or EC2).

Important Note: The policy for the instance profile is highly dangerous given the S3, VPC and IAM related permissions given to it, Terraform needs a wide swath of CRUD permissions and even permissions for things that aren't deployed by the config files. For rolling ElectricEye out in a Production or an otherwise highly regulated environment, consider adding IAM Condition Keys, using CI/CD (no human access) and backing up your Terraform state files to a S3 backend to add guardrails around this deployment. I would avoid adding these permissions to an IAM user, and any roles that use this should only be assumable by where you are deploying it from, consider adding other Condition Keys to the Trust Policy.

In this stage we will install and deploy the ElectricEye infrastructure via Terraform. To securely backup your state file, you should explore the usage of a S3 backend, this is also described in this AWS Security Blog post.

1. Install the dependencies for Terraform.

Note: Ensure this is the latest version of Terraform, since authoring this tool, I do not make use of it anymore and rely on outside contributors to update the Configs.

wget https://releases.hashicorp.com/terraform/0.14.4/terraform_0.14.4_linux_amd64.zip
unzip terraform_0.14.4_linux_amd64.zip
sudo mv terraform /usr/local/bin/
terraform --version

2. Change directories and modify the variables.tf config file to include the URI of your Docker image and the name of your ECR Repository as shown in the screenshot below. Optionally replace the values of the Shodan API Key, DisruptOps Client Id, and DisruptOps API Key parameters with yours if you created them in the previous optional steps.

cd terraform-config-files
nano variables.tf

3. Initialize, plan and apply your state with Terraform, this step should not take too long.

terraform init
terraform plan
terraform apply -auto-approve

4. Navigate to the S3 console and locate the name of the S3 bucket created by Terraform for the next step. It should be in the format of electriceye-artifact-bucket-(AWS_REGION)-(ACCOUNT-NUMBER) if you left everything else default in variables.tf

5. Navigate to the auditors directory and upload the code base to your S3 bucket

cd -
cd eeauditor/auditors/aws
aws s3 sync . s3://<your-bucket-name>

6. Navigate to the insights directory and execute the Python script to have Security Hub Insights created. Insights are saved searches that can also be used as quick-view dashboards (though nowhere near the sophistication of a QuickSight dashboard)

cd -
cd insights
python3 electriceye-insights.py

In the next stage you will launch the ElectricEye ECS task manually because after Terraform deploys this solution it will automatically run, and it will fail due to a lack of Auditor scripts in the S3 bucket.

1. Download the CloudFormation template and create a Stack. Refer to the Get Started section of the AWS CloudFormation User Guide if you have not done this before.

2. Enter the URI of the Docker image in the space for the parameter ElectricEyeContainerInfo. Leave all other parameters as the default value, unless you already used 10.77.0.0/16 as the CIDR for one of your VPCs and plan to attach this VPC to your T-Gateway. Optionally replace the values of the Shodan API Key, DisruptOps Client Id, and DisruptOps API Key parameters with yours if you created them in the previous optional steps and then create your stack.

NOTE: The Terraform implementation applies a resource-based repository policy that only allows access to the ElectricEye ECS IAM Roles (Execution & Task), if you want to apply something similar for CloudFormation you will need to issue the following ECR CLI command:

aws ecr set-repository-policy \
    --repository-name <ECR_REPO_NAME> \
    --policy-text file://my-policy.json

You can create my-policy.json with the below example, replace the values for <Task_Execution_Role_ARN> and <Task_Role.arn> as needed.

{
  "Version": "2008-10-17",
  "Statement": [
    {
      "Sid": "new statement",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "<Task_Execution_Role_ARN>",
          "<Task_Role.arn>"
        ],
        "Service": "ecs-tasks.amazonaws.com"
      },
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:DescribeRepositories",
        "ecr:GetAuthorizationToken",
        "ecr:GetDownloadUrlForLayer",
        "ecr:GetRepositoryPolicy",
        "ecr:ListImages"
      ]
    }
  ]
}

3. Navigate to the S3 console and locate the name of the S3 bucket created by CloudFormation for the next step. It should be in the format of electric-eye-artifact-bucket--(AWS_REGION)-(ACCOUNT-NUMBER)

4. Navigate to the auditors directory and upload the code base to your S3 bucket

cd -
cd eeauditor/auditors/aws
aws s3 sync . s3://<your-bucket-name>

5. Navigate to the insights directory and execute the Python script to have Security Hub Insights created. Insights are saved searches that can also be used as quick-view dashboards (though nowhere near the sophistication of a QuickSight dashboard)

cd -
cd insights
python3 electriceye-insights.py

In this stage we will use the console the manually run the ElectricEye ECS task, it is optional.

1. Navigate to the ECS Console, select Task Definitions and toggle the electric-eye task definition. Select the Actions dropdown menu and select Run Task as shown in the below screenshot.

2. Configure the following settings in the Run Task screen as shown in the screenshot below.

• Launch type: Fargate
• Platform version: LATEST
• Cluster: electric-eye-vpc-ecs-cluster (unless named otherwise)
• Number of tasks: 1
• Task group: LEAVE THIS BLANK
• Cluster VPC: electric-eye-vpc
• Subnets: any eletric eye Subnet
• Security groups: electric-eye-vpc-sec-group (you will need to select Modify and choose from another menu)
• Auto-assign public IP: ENABLED

3. Select Run task, in the next screen select the hyperlink in the Task column and select the Logs tab to view the result of the logs. Note logs coming to this screen may be delayed, and you may have several auditors report failures due to the lack of in-scope resources.

These are the following services and checks perform by each Auditor. There are currently 💥 512 Checks 💥 supported across ❗ 93 AWS services/components ❗ with a total of 🔥 72 Auditors 🔥 .

There are currently 62 supported response and remediation Playbooks with coverage across 32 AWS services / components supported by ElectricEye-Response.

Regarding AWS ElasticSearch Service/OpenSearch Service: AWS has stopped supporting Elastic after Version 7.10 and released a new service named OpenSearch. The APIs/SDKs/CLI are interchangable. Only ASFF metadata has changed to reflect this, the Auditor Names, Check Names, and ASFF ID's have stayed the same.

Regarding Shield Advanced, Health, and Trusted Advisor checks: You must be subscribed to Shield Advanced, be on Business/Enterprise Support and be in us-east-1 to perform all checks. The AWS Shield Advanced, AWS Health and AWS Trusted Advisor APIs only live in us-east-1, and to have the DRT look at your account you need Biz/Ent support, hence the pre-reqs.

Regarding Security Group checks: The table shows the full amount of checks despite not being shown in the CLI due to the change to a Configuation-file based approach added on 25 MAR 2022.

The following are optional add-on's to ElectricEye that will extend its functionality via reporting, alerting, enrichment and/or finding lifecycle management.

• ElectricEye-Response

  • ElectricEye-Response is a multi-account automation framework for response and remediation actions heavily influenced by work I did when employed by AWS. From your Security Hub Master, you can launch response and remediation actions by using CloudWatch Event rules, Lambda functions, Security Token Service (STS) and downstream services (such as Systems Manager Automation or Run Command). You can run these in a targetted manner (using Custom Actions) or fully automatically (using the CloudWatch detail type of Security Hub Findings - Imported).

• ElectricEye-ChatOps

  • ElectricEye-ChatOps utilizes EventBridge / CloudWatch Event Rules to consume HIGH and CRITICAL severity findings created by ElectricEye from Security Hub and route them to a Lambda function. Lambda will parse out certain elements from the Security Hub finding, create a message and post it to a Slack App's webhook for consumption by your security engineers or other personnel in a Slack channel.

• ElectricEye-Reports

  • ElectricEye-Reports is an add-on that allows you the created detailed business intelligence (BI) reports from ElectricEye findings in Security Hub using Amazon QuickSight, a "...scalable, serverless, embeddable, machine learning-powered business intelligence (BI) service built for the cloud." Using QuickSight, you can create detailed reports that breakdown all of your ElectricEye findings by Severity, Region, Resource Type, as well as breakout by-Compliance Control reporting and further enrich the dataset in this solution with business-context such as Cost Center, Division, Business Owner, and other metadata. With this data you can create visualizations that can be used by a many Personas across Information Security, IT Audit, IT Operations, Product Development, and Risk functions - such as tracking compliance with specific controls, measuring Key Risk Indicators (KRIs), or preparing evidence for a formal audit certification/attestation/examination.

• ElectricEye-Pagerduty-Integration

  • The Pagerduty integration for ElectricEye, like ElectricEye-ChatOps, utilizes EventBridge / CloudWatch Event Rules to consume HIGH and CRITICAL severity findings created by ElectricEye from Security Hub and route them to a Lambda function. Lambda will parse out certain elements from the Security Hub finding such as the title, remediation information and resource information and to form a Pagerduty Incident to be sent using the EventsV2 API. Pagerduty is an on-call management / incident management tool that has built-in intelligence and automation to route escalations, age-off incidents and can be integrated downstream with other tools.

This section is likely to wax and wane depending on future releases, PRs and changes to AWS APIs.

• If you choose to build and run ElectricEye without the IAC on your own and use an existing VPC or, in the future, decide to build internet-facing services in the ElectricEye VPC you may run into Shodan.io false positives. The socket python module will use the DNS servers available to them; getting the IPv4 address for a DNS name (from RDS or ES endpoints for example) in your VPC will return the private IP address and lead to false positives with Shodan

• No tag-based scoping or exemption process out of the box. You will need to manually archive these, remove checks not pertinent to you and/or create your own automation to automatically archive findings for resources that shouldn't be in-scope.

• Some resources, such as Elasticsearch Service or Elastic File System, cannot be changed after creation for some checks and will continue to show as non-compliant until you manually migrate them, or create automation to auto-archive these findings.

• If Shodan is not working you may be getting throttled, the free tier is supposed to be 1 TPS (I've definitely hit closer to 20 TPS without issue), but it may happen. Or, you didn't rebuild the Docker image which has included requests since 12 MAR 2020. Pass a --no-cache flag if you're rebuilding on the same machine.

• Sometimes copy and pasting the Auditors and script.sh to a S3 bucket via console from a Windows machine will carry over the bad line endings I sometimes accidently include from my own dirty Windows machine. Use the AWS CLI to copy over the files after a cloning / pulling this repo to avoid that, if you've already cloned do this:

cd ElectricEye
git pull
cd auditors
aws s3 sync . s3://<my-bucket-full-o-auditors>

1. Naming an auditor: To keep naming consistent auditor names are based on the name of the service from the AWS Documentation and are named after the service being audited.

2. Necessary Imports and Intro: At the top of the auditor insert the following intro and imports (although other imports may be needed)

# This file is part of ElectricEye.

# ElectricEye is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# ElectricEye is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License along with ElectricEye.
# If not, see https://github.com/jonrau1/ElectricEye/blob/master/LICENSE.

import boto3
import datetime
from check_register import CheckRegister

registry = CheckRegister()

The boto3 client will also need imported for whichever service is being audited. You can get these from the Boto3 Documentation website, but for example, the client for EC2 Image Build is below. To match the style of other Auditors, the variable name should closely (preferably, exactly) match the name of the Client.

imagebuilder = boto3.client("imagebuilder")

NOTE If a boto call is used multiple times within an auditor and could be put in the global space it should be cached. For example in Amazon_SNS_Auditor list_topics is used for every function so it is cached like this:

def list_topics(cache):
    response = cache.get("list_topics")
    if response:
        return response
    cache["list_topics"] = sns.list_topics()
    return cache["list_topics"]

NOTE 2: For Auditors that expect to scan dozens or hundreds of potential resources, it is apt to use a Paginator instead of the standard Describe call due to upper limits (usually 100-500 per "regular" call). The below example is a cached Paginator from the EC2 Auditor with filters.

def paginate(cache):
    response = cache.get("paginate")
    if response:
        return response
    get_paginators = ec2.get_paginator("describe_instances")
    if get_paginators:
        cache["paginate"] = get_paginators.paginate(Filters=[{'Name': 'instance-state-name','Values': ['running','stopped']}])
        return cache["paginate"]

3. Registering and Defining Checks: All checks are registered by the same tag and checks should describe what is being checked with the word check at the end. Example from ImageBuilder. Directly underneath the function that defines the Check should be a single-line, double-quoted comment which contains the Title of the Check. This is outputted by the --list-checks flag in the Controller.

@registry.register_check("imagebuilder")
def imagebuilder_pipeline_tests_enabled_check(cache: dict, awsAccountId: str, awsRegion: str, awsPartition: str) -> dict:
"""[ImageBuilder.1] Image pipeline tests should be enabled"""

4. Formatting Findings: Findings will be formatted for AWS Security Hub, ASSF. Look to other auditors findings format for more specifics on ElectricEye formatting. Parts that will stay consistent across checks are: SchemaVersion, ProductArn, AwsAccountId, FirstObservedAt, CreatedAt, UpdatedAt, ProductFields.Product Name (ElectricEye), and the Resources array. Example finding formatting from Amazon_EC2_Auditor's IMDSv2 Check:

NOTE: While not required by ASFF, it is required by ElectricEye that all checks are mapped to the supported compliance standards. It is recommended to use the mapped Compliance.Requirements from an existing Check within an Auditor that is similar to yours - for instance - if you are developing a check around TLS, look for an example of a Check for encryption in transit. If you are developing a check to enable Logging, look for a Check that deals with Logging.

NOTE 2: The Resources.Id should ALWAYS be an ARN, not every Boto3 Client nor Function within will return an ARN and you may need to look up what the ARN looks like, refer to the Actions, resources, and condition keys for AWS services section of the Service Authorization Reference.

NOTE 3: When possible, ALWAYS use the AWS Documentation for the Remediation.Recommendation.Text and Remediation.Recommendation.Url sections of the ASFF. You should include a short description and note what Section and which Guide you are using. This additional meta-descriptiveness sould also be applied to the Description of a failing finding, as demonstrated below.

finding = {
    "SchemaVersion": "2018-10-08",
    "Id": instanceArn + "/ec2-imdsv2-check",
    "ProductArn": f"arn:{awsPartition}:securityhub:{awsRegion}:{awsAccountId}:product/{awsAccountId}/default",
    "GeneratorId": instanceArn,
    "AwsAccountId": awsAccountId,
    "Types": [
        "Software and Configuration Checks/AWS Security Best Practices",
        "Effects/Data Exposure"
    ],
    "FirstObservedAt": iso8601Time,
    "CreatedAt": iso8601Time,
    "UpdatedAt": iso8601Time,
    "Severity": {"Label": "MEDIUM"},
    "Confidence": 99,
    "Title": "[EC2.1] EC2 Instances should be configured to use instance metadata service V2 (IMDSv2)",
    "Description": "EC2 Instance "
    + instanceId
    + " is not configured to use instance metadata service V2 (IMDSv2). IMDSv2 adds new “belt and suspenders” protections for four types of vulnerabilities that could be used to try to access the IMDS. These new protections go well beyond other types of mitigations, while working seamlessly with existing mitigations such as restricting IAM roles and using local firewall rules to restrict access to the IMDS. Refer to the remediation instructions if this configuration is not intended",
    "Remediation": {
        "Recommendation": {
            "Text": "To learn how to configure IMDSv2 refer to the Transitioning to Using Instance Metadata Service Version 2 section of the Amazon EC2 User Guide",
            "Url": "https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html#instance-metadata-transition-to-version-2",
        }
    },
    "ProductFields": {"Product Name": "ElectricEye"},
    "Resources": [
        {
            "Type": "AwsEc2Instance",
            "Id": instanceArn,
            "Partition": awsPartition,
            "Region": awsRegion,
            "Details": {
                "AwsEc2Instance": {
                    "Type": instanceType,
                    "ImageId": instanceImage,
                    "VpcId": vpcId,
                    "SubnetId": subnetId,
                    "LaunchedAt": parse(instanceLaunchedAt).isoformat(),
                }
            },
        }
    ],
    "Compliance": {
        "Status": "FAILED",
        "RelatedRequirements": [
            "NIST CSF PR.AC-4",
            "NIST SP 800-53 AC-1",
            "NIST SP 800-53 AC-2",
            "NIST SP 800-53 AC-3",
            "NIST SP 800-53 AC-5",
            "NIST SP 800-53 AC-6",
            "NIST SP 800-53 AC-14",
            "NIST SP 800-53 AC-16",
            "NIST SP 800-53 AC-24",
            "AICPA TSC CC6.3",
            "ISO 27001:2013 A.6.1.2",
            "ISO 27001:2013 A.9.1.2",
            "ISO 27001:2013 A.9.2.3",
            "ISO 27001:2013 A.9.4.1",
            "ISO 27001:2013 A.9.4.4",
            "ISO 27001:2013 A.9.4.5"
        ]
    },
    "Workflow": {"Status": "NEW"},
    "RecordState": "ACTIVE"
}
yield finding

5. Creating Tests: For each check within an auditor there should be a corresponding test for each case the check could come across, often times a pass and fail but sometimes more. A stubber is used to give the auditor the desired responses for testing. Necessary imports are:

import datetime
import os
import pytest
import sys

from botocore.stub import Stubber, ANY

6. Update the three IAM Permissions documents within policies/ElectricEye_ECS_Task_Role_Policy.json, cloudformation/ElectricEye_CFN.yaml (in the ElectricEyeTaskRole Logical ID), and terraform-config-files/electric_eye.tf (in the Electric_Eye_Task_Role_Policy Resource).

7. Update the Table within the Supported Services and Checks section and its above description above for total count of auditors/checks and the new checks are added to the list. It is recommended to use Markdown Tables generator by copying and pasting the current table into the website's UI (underneath the File/Paste table data... dropdown menu) and remove the whitespace / added columns for this task.

1. Install dependencies

pip3 install -r requirements-dev.txt

2. Run pytest

pytest

Tests are located in the eeauditor tests folder and individual test can be run by adding the path with the name of the file after pytest.

I am very happy to accept PR's for the following:

• Adding new Auditors
• Adding new checks to existing Auditors
• Adding new ElectricEye-Response playbooks
• Adding new Event Patterns for ElectricEye-ChatOps
• Fixing my stupid grammar errors, spelling errors and inconsistencies
• Removing any unused IAM permissions that may have popped up
• Adding Terraform v0.12.x support

Quick shout-outs to the folks who answered the call early to test out ElectricEye and make it not-a-shit-sandwich.

• Mark Yancey

• Martin Klie
• Joel Castillo
• Juhi Gupta
• Bulent Yidliz
• Guillermo Ojeda
• Dhilip Anand Shivaji
• Arek Bar
• Ryan Russel
• Jonathan Nguyen
• Jody Brazil
• Dylan Shields
• Manuel Leos Rivas
• Andrew Alaniz
• Christopher Childers

As of 12 MAR 2020, most of these items will be tracked on the roadmap project board

• Create an ElectricEye Logo
• Add in Shodan.io checks for internet-facing resources (RDS, Redshift, DocDB, Elasticsearch, EC2, ELBv2, etc)
• Upload response and remediation playbooks and IAC for them - Custom Action Version (Semi Auto)
• Upload response and remediation playbooks and IAC for them - Imported Findings (Full Auto)
• Create an Alerting framework with ChatBot Slack for Critical findings
• Create a Reporting module for use with QuickSight

This library is licensed under the Apache-2.0 License. See the LICENSE file.