electriceye/electriceye repository overview

⁠ElectricEye on Docker

⁠REFER TO THE MAIN REPO⁠ for more detailed information!!!!!!

After configuring ElectricEye for your environment(s) using the TOML configuration⁠, you can instead utilize Docker to run ElectricEye which have images maintained on ECR Public, Oracle Cloud Container Registry (OCR), and Docker Hub. You can read more about the security assurance activities here⁠, in the future more Registries and image signing will be utilized.

⁠Building Images

If you would rather build your own image use the following commands. Be sure to add sudo if you do not have a docker user properly setup in your system.

git clone https://github.com/jonrau1/ElectricEye.git
cd ElectricEye
docker build -t electriceye:local .

From here you can push to your repository of choice, be sure to change the tag from local to whichever tag your repository is expecting or whatever you prefer. Maybe just latest, like a decabillionaire sigma grindset gigachad?

⁠Pulling Images

You can also pull an ElectricEye image from the various repositories, a latest image tag will always be pushed alongside an image tagged with the SHA hash of the workflow ${{ github.sha }} and can be viewed within the various GitHub Action Workflows within the Print Image step.

To pull from the various repositories, use these commands, you can replace latest as you see fit. The dependencies within ElectricEye stay relatively stable until a new cloud or major integration is added. Check the Pull Requests for more information to be sure.

• Amazon Elastic Container Registry (ECR) Public: docker pull public.ecr.aws/t4o3u7t2/electriceye:latest

• Oracle Cloud Infrastructure Registry (OCIR): docker pull iad.ocir.io/idudmagprsdi/electriceye:latest

• Docker Hub: docker pull electriceye/electriceye

⁠Setting up a Session

⁠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⁠ 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.

If you are using a User, proceed to the next step, you will need to have your credentials ready to copy. If you are using an EC2 Instance Profile or an additional IAM Role you will Assume, ensure you have jq installed: apt install -y jq or yum install jq.

AWS_ACCOUNT_ID=$(aws sts get-caller-identity | jq -r '.Account')
MY_ROLE_NAME='iam-role-name'
TEMP_CREDS=$(aws sts assume-role --role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/$MY_ROLE_NAME --role-session-name ElectriceyeForDocker)
AWS_ACCESS_KEY=$(echo $TEMP_CREDS | jq -r '.Credentials.AccessKeyId')
AWS_SECRET_KEY=$(echo $TEMP_CREDS | jq -r '.Credentials.SecretAccessKey')
AWS_SESSION_TOKEN=$(echo $TEMP_CREDS | jq -r '.Credentials.SessionToken')
MY_REGION='aws-region-here'

MY_INSTANCE_PROFILE_ROLE_NAME="my_ec2_role_name"
IMDS_SECURITY_CREDENTIALS=$(curl http://169.254.169.254/latest/meta-data/iam/security-credentials/$MY_INSTANCE_PROFILE_ROLE_NAME)
MY_REGION='my_aws_region'
AWS_ACCESS_KEY=$(echo $IMDS_SECURITY_CREDENTIALS | jq -r '.AccessKeyId')
AWS_SECRET_KEY=$(echo $IMDS_SECURITY_CREDENTIALS | jq -r '.SecretAccessKey')
AWS_SESSION_TOKEN=$(echo $IMDS_SECURITY_CREDENTIALS | jq -r '.Token')

MY_INSTANCE_PROFILE_ROLE_NAME="my_ec2_role_name"
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 300")
IMDSV2_SECURITY_CREDENTIALS=$(curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/security-credentials/$MY_INSTANCE_PROFILE_ROLE_NAME)
MY_REGION='my_aws_region'
AWS_ACCESS_KEY=$(echo $IMDSV2_SECURITY_CREDENTIALS | jq -r '.AccessKeyId')
AWS_SECRET_KEY=$(echo $IMDSV2_SECURITY_CREDENTIALS | jq -r '.SecretAccessKey')
AWS_SESSION_TOKEN=$(echo $IMDSV2_SECURITY_CREDENTIALS | jq -r '.Token')

You can also retrieve temporary credentials from Federated identities, read more at the links for AssumeRoleWithWebIdentity⁠ or AssumeRoleWithSAML⁠ or refer to the larger temporary credential documentation here⁠.

⁠Running ElectricEye Container

Run ElectricEye using the following commands, passing in your Session credentials. Change the commands within the container to evaluate different environments with ElectricEye. Change the value of /path/to/my/external_providers.toml to your exact path, such as ~/electriceye-docker/external_providers.toml for example.

IMPORTANT NOTE If you are using an AWS IAM User with Access Keys, hardcode the values and omit the value for AWS_SESSION_TOKEN!!

sudo docker run \
    --user eeuser:eeuser \
    -e AWS_DEFAULT_REGION=$MY_REGION \
    -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY \
    -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_KEY \
    -e AWS_SESSION_TOKEN=$AWS_SESSION_TOKEN \
    -v /path/to/my/external_providers.toml:/eeauditor/external_providers.toml \
    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.

BUCKET_NAME="your_s3_bucket_you_have_access_to"
sudo docker run \
    --user eeuser:eeuser \
    -e AWS_DEFAULT_REGION=$MY_REGION \
    -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY \
    -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_KEY \
    -e AWS_SESSION_TOKEN=$AWS_SESSION_TOKEN \
    -v /path/to/my/external_providers.toml:/eeauditor/external_providers.toml \
    electriceye /bin/bash -c "python3 eeauditor/controller.py -t AWS -o json --output-file /eeauditor/my-aws-findings \
    && aws s3 cp /eeauditor/my-aws-findings.json s3://$BUCKET_NAME/eefindings.json"

For more configuration information ensure you refer back to the per-Provider setup instructions.