{"id":13533428,"url":"https://github.com/jonrau1/ElectricEye","last_synced_at":"2025-04-01T21:32:25.344Z","repository":{"id":37904253,"uuid":"238931093","full_name":"jonrau1/ElectricEye","owner":"jonrau1","description":"ElectricEye is a multi-cloud, multi-SaaS Python CLI tool for Asset Management, Security Posture Management \u0026 Attack Surface Monitoring supporting 100s of services and evaluations to harden your CSP \u0026 SaaS environments with controls mapped to over 20 industry, regulatory, and best practice controls frameworks","archived":false,"fork":false,"pushed_at":"2024-05-06T03:22:22.000Z","size":98223,"stargazers_count":864,"open_issues_count":7,"forks_count":117,"subscribers_count":34,"default_branch":"master","last_synced_at":"2024-05-06T04:28:59.430Z","etag":null,"topics":["asset-management","attack-surface-management","aws","aws-audit","aws-compliance","aws-security","cloud-auditing","cloud-compliance-reporting","cloud-security","compliance","devsecops","gcp-security","google-cloud-security","multicloud","saas-security","security-audit","security-engineering","security-hub","security-monitoring","security-tools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonrau1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-07T13:32:16.000Z","updated_at":"2024-06-20T04:00:30.380Z","dependencies_parsed_at":"2023-02-01T05:15:41.142Z","dependency_job_id":"a36c920f-5530-4174-8451-b3f2fa543757","html_url":"https://github.com/jonrau1/ElectricEye","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonrau1%2FElectricEye","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonrau1%2FElectricEye/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonrau1%2FElectricEye/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonrau1%2FElectricEye/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonrau1","download_url":"https://codeload.github.com/jonrau1/ElectricEye/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246713403,"owners_count":20821883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asset-management","attack-surface-management","aws","aws-audit","aws-compliance","aws-security","cloud-auditing","cloud-compliance-reporting","cloud-security","compliance","devsecops","gcp-security","google-cloud-security","multicloud","saas-security","security-audit","security-engineering","security-hub","security-monitoring","security-tools"],"created_at":"2024-08-01T07:01:19.756Z","updated_at":"2025-04-01T21:32:20.334Z","avatar_url":"https://github.com/jonrau1.png","language":"Python","funding_links":[],"categories":["AWS","Python","Infrastructure","Tools","security-tools","aws","AWS Security"],"sub_categories":["Defensive"],"readme":"# ElectricEye\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./screenshots/logo.svg\" width=\"420\" height=\"420\"\u003e\n\u003c/p\u003e\n\nElectricEye is a multi-cloud, multi-SaaS Python CLI tool for Asset Management, Security Posture Management \u0026 Attack Surface Monitoring supporting 100s of services and evaluations to harden your CSP \u0026 SaaS environments with controls mapped to over 20 industry, regulatory, and best practice controls frameworks.\n\n![VulnScan](https://github.com/jonrau1/ElectricEye/actions/workflows/sbom-vulns.yml/badge.svg)  ![CodeQL](https://github.com/jonrau1/ElectricEye/actions/workflows/codeql-analysis.yml/badge.svg) ![EcrBuild](https://github.com/jonrau1/ElectricEye/actions/workflows/push-ecr-public.yml/badge.svg) ![OcrBuild](https://github.com/jonrau1/ElectricEye/actions/workflows/push-ocr-public.yml/badge.svg) ![DockerHubBuild](https://github.com/jonrau1/ElectricEye/actions/workflows/push-docker-hub.yml/badge.svg)\n\n\u003cp\u003e\n  \u003ca href=\"https://hub.docker.com/r/electriceye/electriceye\"\u003e\u003cimg alt=\"Docker Pulls\" src=\"https://img.shields.io/docker/pulls/electriceye/electriceye\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/r/electriceye/electriceye\"\u003e\u003cimg alt=\"Docker\" src=\"https://img.shields.io/docker/image-size/electriceye/electriceye\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/jonrau1/ElectricEye\"\u003e\u003cimg alt=\"Repo size\" src=\"https://img.shields.io/github/repo-size/jonrau1/ElectricEye\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/jonrau1/ElectricEye/issues\"\u003e\u003cimg alt=\"Issues\" src=\"https://img.shields.io/github/issues/jonrau1/ElectricEye\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/jonrau1/ElectricEye\"\u003e\u003cimg alt=\"Contributors\" src=\"https://img.shields.io/github/contributors-anon/jonrau1/ElectricEye\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/jonrau1/ElectricEye\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/jonrau1/ElectricEye\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://gallery.ecr.aws/t4o3u7t2/electriceye\"\u003e\u003cimg width=\"150\" height=\"40\" padding=\"5\" alt=\"AWS ECR Gallery\" src=\"https://user-images.githubusercontent.com/3985464/151531396-b6535a68-c907-44eb-95a1-a09508178616.png\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://hub.docker.com/r/electriceye/electriceye\"\u003e\u003cimg width=\"150\" height=\"40\" padding=\"5\" alt=\"Docker Hub\" src=\"https://www.unixtutorial.org/images/software/docker-hub.png\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n***Up here in space***\u003cbr/\u003e\n***I'm looking down on you***\u003cbr/\u003e\n***My lasers trace***\u003cbr/\u003e\n***Everything you do***\u003cbr/\u003e\n\u003csub\u003e*Judas Priest, 1982*\u003c/sub\u003e\n\n## Table of Contents\n\n- [Workflow](#workflow)\n- [Quick Run Down](#quick-run-down-running-running)\n- [Configuring ElectricEye](#configuring-electriceye)\n- [Cloud Asset Management](#cloud-asset-management-cam)\n- [Supported Services and Checks](#supported-services-and-checks)\n- [ElectricEye on Docker](#electriceye-on-docker)\n- [Outputs](./docs/outputs/OUTPUTS.md)\n- [Contributing](#contributing)\n- [FAQ](#faq)\n- [Developer \u0026 Testing Guide](./docs/new_checks/DEVELOPER_GUIDE.md)\n- [Repository Security](#repository-security)\n- [License](#license)\n\n## Workflow\n\n![Architecture](./screenshots/electrice_eye_architecture.jpg)\n\n## Quick Run Down :running: :running:\n\n- ElectricEye is a Python CLI tool that offers cross-Account, cross-Region, multi-Cloud \u0026 SaaS Asset Management, Security Posture Management, and Attack Surface Monitoring capabilities across [AWS, all Partitions supported!](https://aws.amazon.com/), [GCP](https://cloud.google.com/), [Oracle Cloud Infrastructure (OCI)](https://www.oracle.com/cloud/), [ServiceNow](https://www.servicenow.com/), [Microsoft 365 Enterprise (*M365*)](https://www.microsoft.com/en-us/microsoft-365/compare-microsoft-365-enterprise-plans), [Salesforce (*SFDC*)](https://help.salesforce.com/s), and [Azure](https://portal.azure.com/).\n\n- ElectricEye offers over *1000* Checks against security, resilience, performance, and financial best practices across more than 100 CSP \u0026 SaaS services, including atypical services not supported by CSP/SaaS-native asset management tools/views or mainstream CSPM \u0026 CNAPP tools.\n\n- Every single Check is mapped to over 20 controls frameworks covering general best practices, regulatory, industry-specific, and legal frameworks such as NIST CSF, AICPA TSCs (for SOC 2), the HIPAA Security Rule, NIST 800-171 Rev. 2, CMMC V2.0, European Central Bank's CROE Section 2, PCI-DSS V4.0, CIS Foundations Benchmarks, and more!\n\n- Multi-faceted Attack Surface Monitoring uses tools such as VirusTotal, Nmap, Shodan.io, Detect-Secrets, and CISA's KEV to locate assets indexed on the internet, find exposed services, locate exploitable vulnerabilities, and malicious packages in artifact repositories, respectively.\n\n- Outputs to [AWS Security Hub](https://aws.amazon.com/security-hub/), the [Open Cyber Security Framework (OCSF)](https://github.com/ocsf/) [V1.1.0](https://schema.ocsf.io/1.1.0/?extensions=) in JSON, [AWS DocumentDB](https://aws.amazon.com/documentdb/), JSON, CSV, HTML Reports, [MongoDB](https://www.mongodb.com/), [Amazon SQS](https://aws.amazon.com/sqs/), [PostgreSQL](https://www.postgresql.org/), [Slack](https://slack.com/) (via Slack App Bots), and [FireMon Cloud Defense](https://www.firemon.com/introducing-disruptops/).\n\nElectricEye's core concept is the **Auditor** which are sets of Python scripts that run **Checks** per Service dedicated to a specific SaaS vendor or public cloud service provider called an **Assessment Target**.  You can run an entire Assessment Target, a specific Auditor, or a specific Check within an Auditor. After ElectricEye is done with evaluations, it supports over a dozen types of **Outputs** ranging from an HTML executive report to AWS DocumentDB clusters - you can run multiple Outputs as you see fit.\n\nElectricEye also uses utilizes other tools such as [Shodan.io](https://www.shodan.io/), [Yelp's `detect-secrets`](https://pypi.org/project/detect-secrets/), [VirusTotal](https://www.virustotal.com/gui/home/upload), the [United States Cyber and Infrastructure Security Agency (CISA)](https://www.cisa.gov/) [Known Exploited Vulnerability (KEV)](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) Catalog, and [NMAP](https://nmap.org/) for carrying out its Checks and enriching their findings.\n\n1. First, clone this repository and install the requirements using `pip3`: `pip3 install -r requirements.txt`.\n\n2. If you are evaluating anything other than your local AWS Account, modify the [TOML configuration](./eeauditor/external_providers.toml)  located in `ElectricEye/eeauditor/external_providers.toml`, or provide a path to your own with with `--toml-path`. The TOML file specifies multi-account, mulit-region, credential, and output specifics.\n\n3. Finally, run the Controller to learn about the various Checks, Auditors, Assessment Targets, and Outputs.\n\n```\npython3 eeauditor/controller.py --help\nUsage: controller.py [OPTIONS]\n\nOptions:\n  -t, --target-provider [AWS|Azure|OCI|GCP|Servicenow|M365|Salesforce|Snowflake]\n                                  Public cloud or SaaS assessment target,\n                                  ensure that any -a or -c arg maps to your\n                                  target provider to avoid any errors. e.g.,\n                                  -t AWS -a Amazon_APGIW_Auditor\n  -a, --auditor-name TEXT         Specify which Auditor you want to run by\n                                  using its name NOT INCLUDING .py. . Use the\n                                  --list-checks arg to receive a list.\n                                  Defaults to ALL Auditors\n  -c, --check-name TEXT           A specific Check in a specific Auditor you\n                                  want to run, this correlates to the function\n                                  name. Use the --list-checks arg to receive a\n                                  list. Defaults to ALL Checks\n  -d, --delay INTEGER             Time in seconds to sleep between Auditors\n                                  being ran, defaults to 0. Use this argument\n                                  to avoid rate limiting\n  -o, --outputs TEXT              A list of Outputs (files, APIs, databases,\n                                  ChatOps) to send ElectricEye Findings,\n                                  specify multiple with additional arguments:\n                                  -o csv -o postgresql -o slack  [default:\n                                  ocsf_stdout]\n  -of, --output-file TEXT         For file outputs such as JSON and CSV, the\n                                  name of the file, DO NOT SPECIFY .file_type\n                                  [default: output]\n  -lo, --list-options             Lists all valid Output options\n  -lch, --list-checks             Prints a table of Auditors, Checks, and\n                                  Check descriptions to stdout - use this\n                                  command for help with populating -a (Auditor\n                                  selection) or -c (Check selection) args\n  -lco, --list-controls           Lists all ElectricEye controls - that is to\n                                  say: the Check Titles - for an Assessment\n                                  Target\n  -tp, --toml-path TEXT           The full path to the TOML file used for\n                                  configure e.g.,\n                                  ~/path/to/mydir/external_providers.toml. If\n                                  this value is not provided the default path\n                                  of ElectricEye/eeauditor/external_providers.\n                                  toml is used.\n  --help                          Show this message and exit.\n```\n\nFor more information see [here](#configuring-electricey), you can read the [FAQ here](./docs/faq/FAQ.md), information on [Outputs is here](./docs/outputs/OUTPUTS.md) or, if you want a more in-depth analysis of the control flow and concepts review [the Developer Guide](./docs/new_checks/DEVELOPER_GUIDE.md).\n\n## Configuring ElectricEye\n\nRefer to sub-headings for per-CSP or per-SaaS setup instructions. Go to [Outputs](./docs/outputs/OUTPUTS.md) to, well, learn about Outputs and examples.\n\n### Public Cloud Service Providers\n\n- [For Amazon Web Services (AWS)](./docs/setup/Setup_AWS.md)\n- [For Google Cloud Platform (GCP)](./docs/setup/Setup_GCP.md)\n- [For Oracle Cloud Infrastructure](./docs/setup/Setup_OCI.md)\n- [For Microsoft Azure](./docs/setup/Setup_Azure.md)\n\nThe following Cloud Service Providers are on the Roadmap\n\n- [For Alibaba Cloud (*Coming Soon*)](./docs/setup/Setup_AlibabaCloud.md)\n\n### Software-as-a-Service (SaaS) Providers\n\n- [For ServiceNow](./docs/setup/Setup_ServiceNow.md)\n- [For Microsoft M365](./docs/setup/Setup_M365.md)\n- [For Salesforce](./docs/setup/Setup_Salesforce.md)\n- [For Snowflake](./docs/setup/Setup_Snowflake.md)\n\nThe following SaaS Providers are on the Roadmap\n\n- [For Google Workspaces (*Coming Soon*)](./docs/setup/Setup_Google_Workspaces.md)\n\n## Cloud Asset Management (CAM)\n\nFor more information on ElectricEye's CAM concept of operations and schema, refer to [the Asset Management documentation](./docs/asset_management/ASSET_MANAGEMENT.md).\n\n## Supported Services and Checks\n\nIn total there are:\n\n- **4** Supported Public CSPs: `AWS`, `GCP`, `OCI`, and `Azure`\n- **4** Supported SaaS Providers: `ServiceNow`, `M365`, `Salesforce`, and `Snowflake`\n- **1193** ElectricEye Checks\n- **177** Supported CSP \u0026 SaaS Asset Components across all Services\n- **133** ElectricEye Auditors\n\nThe tables of supported Services and Checks have been migrated to the respective per-Provider setup documentation linked above in [Configuring ElectricEye](#configuring-electriceye).\n\n## ElectricEye on Docker\n\nAfter configuring ElectricEye for your environment(s) using the [TOML configuration](./eeauditor/external_providers.toml), 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](#repository-security), in the future more Registries and image signing will be utilized.\n\n### Building Images\n\nIf 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.\n\n```bash\ngit clone https://github.com/jonrau1/ElectricEye.git\ncd ElectricEye\ndocker build -t electriceye:local .\n```\n\nFrom 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?\n\n### Pulling Images\n\nYou 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.\n\nTo 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.\n\n- Amazon Elastic Container Registry (ECR) Public: `docker pull public.ecr.aws/t4o3u7t2/electriceye:latest` \n\n- Oracle Cloud Infrastructure Registry (OCIR): `docker pull iad.ocir.io/idudmagprsdi/electriceye:latest`\n\n- Docker Hub: `docker pull electriceye/electriceye`\n\n### Setting up a Session\n\n#### 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\n\nWhen 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.\n\nRunning ElectricEye from AWS Infrastructure that has an attached Role, or running from a location with `aws cli` credentials already instantiated, this is handled transparently. \n\nWhen 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.\n\nEnsure 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.\n\nYou will need `sts:AssumeRole` to assume into the Role specified in the `aws_electric_eye_iam_role_name` TOML parameter.\n\nYou 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.\n\nIf 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`.\n\n\u003e - To Assume an IAM Role and retrieve the temporary credentials\n\n```bash\nAWS_ACCOUNT_ID=$(aws sts get-caller-identity | jq -r '.Account')\nMY_ROLE_NAME='iam-role-name'\nTEMP_CREDS=$(aws sts assume-role --role-arn arn:aws:iam::$AWS_ACCOUNT_ID:role/$MY_ROLE_NAME --role-session-name ElectriceyeForDocker)\nAWS_ACCESS_KEY=$(echo $TEMP_CREDS | jq -r '.Credentials.AccessKeyId')\nAWS_SECRET_KEY=$(echo $TEMP_CREDS | jq -r '.Credentials.SecretAccessKey')\nAWS_SESSION_TOKEN=$(echo $TEMP_CREDS | jq -r '.Credentials.SessionToken')\nMY_REGION='aws-region-here'\n```\n\n\u003e - To retrieve temporary credentials for an EC2 Instance Profile using Instance Metadata Service Version 1\n\n```bash\nMY_INSTANCE_PROFILE_ROLE_NAME=\"my_ec2_role_name\"\nIMDS_SECURITY_CREDENTIALS=$(curl http://169.254.169.254/latest/meta-data/iam/security-credentials/$MY_INSTANCE_PROFILE_ROLE_NAME)\nMY_REGION='my_aws_region'\nAWS_ACCESS_KEY=$(echo $IMDS_SECURITY_CREDENTIALS | jq -r '.AccessKeyId')\nAWS_SECRET_KEY=$(echo $IMDS_SECURITY_CREDENTIALS | jq -r '.SecretAccessKey')\nAWS_SESSION_TOKEN=$(echo $IMDS_SECURITY_CREDENTIALS | jq -r '.Token')\n```\n\n\u003e - To retrieve temporary credentials for an EC2 Instance Profile using Instance Metadata Service Version 2\n\n```bash\nMY_INSTANCE_PROFILE_ROLE_NAME=\"my_ec2_role_name\"\nTOKEN=$(curl -X PUT \"http://169.254.169.254/latest/api/token\" -H \"X-aws-ec2-metadata-token-ttl-seconds: 300\")\nIMDSV2_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)\nMY_REGION='my_aws_region'\nAWS_ACCESS_KEY=$(echo $IMDSV2_SECURITY_CREDENTIALS | jq -r '.AccessKeyId')\nAWS_SECRET_KEY=$(echo $IMDSV2_SECURITY_CREDENTIALS | jq -r '.SecretAccessKey')\nAWS_SESSION_TOKEN=$(echo $IMDSV2_SECURITY_CREDENTIALS | jq -r '.Token')\n```\n\nYou can also retrieve temporary credentials from Federated identities, read more at the links for [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) or [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) or refer to the larger temporary credential documentation [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_assumerole).\n\n### Running ElectricEye Container\n\nRun 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.\n\n**IMPORTANT NOTE** If you are using an AWS IAM User with Access Keys, hardcode the values and omit the value for `AWS_SESSION_TOKEN`!! If you are running this container on an AWS container/Kubernetes service you do not need to provide these values!\n\n```bash\nsudo docker run \\\n    --user eeuser:eeuser \\\n    -e AWS_DEFAULT_REGION=$MY_REGION \\\n    -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY \\\n    -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_KEY \\\n    -e AWS_SESSION_TOKEN=$AWS_SESSION_TOKEN \\\n    -v /path/to/my/external_providers.toml:/eeauditor/external_providers.toml \\\n    electriceye /bin/bash -c \"python3 eeauditor/controller.py --help\"\n```\n\nTo 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.\n\nTo 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.\n\nIf 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.\n\n```bash\nBUCKET_NAME=\"your_s3_bucket_you_have_access_to\"\nsudo docker run \\\n    --user eeuser:eeuser \\\n    -e AWS_DEFAULT_REGION=$MY_REGION \\\n    -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY \\\n    -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_KEY \\\n    -e AWS_SESSION_TOKEN=$AWS_SESSION_TOKEN \\\n    -v /path/to/my/external_providers.toml:/eeauditor/external_providers.toml \\\n    electriceye /bin/bash -c \"python3 eeauditor/controller.py -t AWS -o json --output-file /eeauditor/my-aws-findings \\\n    \u0026\u0026 aws s3 cp /eeauditor/my-aws-findings.json s3://$BUCKET_NAME/eefindings.json\"\n```\n\nFor more configuration information ensure you refer back to the per-Provider setup instructions.\n\n## Contributing\n\nRefer to the [Developer Guide](./docs/new_checks/DEVELOPER_GUIDE.md) for instructions on how to produce new checks, for new SaaS and CSP support please open an Issue.\n\nFeel free to open PRs and Issues where syntax, grammatic, and implementation errors are encountered in the code base.\n\n### ElectricEye is for sale\n\nHit 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.\n\n### Early Contributors\n\nQuick shout-outs to the folks who answered the call early to test out ElectricEye and make it not-a-shit-sandwich.\n\n##### Alpha Testing:\n\n- [Mark Yancey](https://www.linkedin.com/in/mark-yancey-jr-aspiring-cloud-security-professional-a52bb9126/)\n\n##### Beta Testing:\n\n- [Martin Klie](https://www.linkedin.com/in/martin-klie-0600845/)\n- [Joel Castillo](https://www.linkedin.com/in/joelbcastillo/)\n- [Juhi Gupta](https://www.linkedin.com/in/juhi-gupta-09/)\n- [Bulent Yidliz](https://www.linkedin.com/in/bulent-yildiz/)\n- [Guillermo Ojeda](https://www.linkedin.com/in/guillermoojeda/)\n- [Dhilip Anand Shivaji](https://www.linkedin.com/in/dhilipanand/)\n- [Arek Bar](https://www.linkedin.com/in/arkadiuszbar/)\n- [Ryan Russel](https://www.linkedin.com/in/pioneerrussell/)\n- [Jonathan Nguyen](https://www.linkedin.com/in/jonanguyen/)\n- [Jody Brazil](https://www.linkedin.com/in/jodybrazil/)\n- [Dylan Shields](https://www.linkedin.com/in/dylan-shields-6802b1168/)\n- [Manuel Leos Rivas](https://www.linkedin.com/in/manuel-lr/)\n- [Andrew Alaniz](https://www.linkedin.com/in/andrewdalaniz/)\n- [Christopher Childers](https://www.linkedin.com/in/christopher-childers-28950537/)\n\n## FAQ\n\nThis is done Amazonian-style, which is to say, none of these questions are frequently asked and are supposed to help Product Managers figure out if their ideas are good...\n\nThat said, some of these questions do get asked. So, you're welcome.\n\n### 1. What is ElectricEye?\n\nElectricEye is an agentless Python Command Line Interface (CLI) tool that scans and evaluates Cloud Service Providers (CSPs) and Software-as-a-Service (SaaS) Vendors for service-level configurations. ElectricEye generates a passing or failing finding per resource across multiple checks that align to seucirty posture management best practices as well as other hygeine checks such as resiliency, recovery, performance optimization, and monitoring. ElectricEye covers popular providers such as AWS, GCP, ServiceNow, and more.\n\n### 2. Who should use ElectricEye?\n\nElectricEye can be used by any persona within a cloud organization in the security or IT functions such as (but not limited to) Security Engineers, Dev(Sec)Ops Engineers, SREs/Platform Engineers, Architects (various flavors), Governance/Risk/Compliance Analysts, SOC/SecOps Analysts, Cloud Advisors, Offensive Security (Red/Blue/Purple) Teams, and 3rd Party Risk Management Analysts. ElectricEye can also be used by IT Operations, Technology Business Management/ITFM Analysts, and Business Continuity Analysts, and Asset Managers as ElectricEye offers native Cloud Asset Management capabilities.\n\n### 3. Why should someone use ElectricEye?\n\nElectricEye should be used by anyone wanting to ensure their cloud vendors and their full breadth of services are configured to ensure the best security hygeine. ElectricEye has the most service coverage offering and is the only dual-use Security Posture Management (SPM) tool that is offered for free for both Cloud Security Posture Management (CSPM) and SaaS Security Posture Management (SSPM). ElectricEye also comes with built-in secrets detection and External Attack Surface Management (EASM) capabilities as well as Cloud Asset Management (CAM) with its own hierarchy to support cross-cloud, cross-boundary asset management and reporting.\n\n### 4. Is ElectricEye a CSPM?\n\nYes, ElectricEye is a Cloud Security Posture Management (CSPM) tool, it provides API-based (agentless) scans of cloud infrastructure and ensures services are configured to best practices.\n\n### 5. Is ElectricEye a SSPM?\n\nYes, ElectricEye is a SaaS Security Posture Management (SSPM) tool, it provides API-based (agentless) scans of SaaS vendor APIs and ensures users and services are configured to best practices.\n\n### 6. Is ElectricEye a CIEM?\n\nNo, ElectricEye is not a Cloud Infrastructure Entitlement Management (CIEM) tool, while ElectricEye does provide several Identity \u0026 Access Management checks and does per-user evaluations for MFA, password rotation, and permissions minimization it is not a CIEM. ElectricEye does not have widespread policy evaluation across multiple identity brokers, providers, and boundaries nor does ElectricEye provide any remediation or Just In Time (JIT) entitlements management capabilities.\n\n### 7. Is ElectricEye a SIEM?\n\nNo, ElectricEye is not a Security Information \u0026 Event Management (SIEM) tool. SIEM tools are used to collect, index, and correlate logs, security events, and other semi-structured and structured data for security operations use cases. While ElectricEye findings can be sent to a SIEM, ElectricEye is not a SIEM in its own right.\n\n### 8. Is ElectricEye an Audit / Compliance Tool?\n\nNo, ElectricEye is not *directly* an Audit or Compliance tool. While every finding is mapped into popular and well-used security compliance regimes such as NIST CSF v1.1 and AICPA 2020 TSCs, ElectricEye only provides best-effort mappings for controls and is not the same as an Auditor or other qualified assessor auditing your environment. ElectricEye can be used as an audit readiness or preparedness tool, you could take samples of findings if the cloud infrastructure controls are important to your overall security program. Controls are technical or administrative (i.e., policy or procedure) countermeasures designed to protect the desired outcomes of a security or privacy program. Controls protect the confidentiality, integrity, and availability of information systems. ElectricEye can help determine if the configurations of your cloud infrastructure meets the \"spirit\" of the controls but is **NOT** the same as an attestation, certification, or some other occult ritual.\n\n### 9. What is \"Audit Readiness\" ?\n\nElectricEye uses the term Audit Readiness when communicating the intended use cases for its control frameworks mappings. ElectricEye could be used by qualified assessors to evaluate your environment, it could be used by you to provide as evidence to assessors, but it's best used case is preparing or seeing your readiness for an audit. However, you should already have your own internal controls defined and your own configuration management strategy when it comes to implementing controls. For instance, you may decide it costs too much money and does not offer many security benefits to encrypt all your SQS Queues with AWS KMS CMKs, you have to do that \"groundwork\" before using ElectricEye to support your internal GRC processes.\n\n### 10. What control frameworks does ElectricEye support?\n\nThe controls frameworks that ElectricEye supports is always being updated as newer versions and mappings are available, as of 21 JUNE 2024 the following standards, frameworks, and legal requirements are supported.\n\n- NIST Cybersecurity Framework Version 1.1\n- NIST Special Publication 800-53 Revision 4\n- NIST Special Publication 800-53 Revision 5\n- NIST Special Publication 800-171 Revision 2\n- American Institute of Certified Public Accountants (AICPA) Trust Service Criteria (TSC) 2017/2020 for SOC 2\n- ISO/IEC 27001:2013/2017 Annex A\n- ISO/IEC 27001:2022 Annex A\n- Center for Internet Security (CIS) Critical Security Controls Version 8\n- Cloud Security Alliance (CSA) Cloud Controls Matrix (CCM) Version 4.0\n- United States Department of Defense Cybersecurity Maturity Model Certification (CMMC) Version 2.0\n- United States Federal Bureau of Investigation (FBI) Criminal Justice Information System (CJIS) Security Policy Version 5.9\n- United Kingdom National Cybercrime Security Center (NCSC) Cyber Essentials Version 2.2\n- United Kingdom National Cybercrime Security Center (NCSC) Assessment Framework Version 3.1\n- HIPAA \"Security Rule\" U.S. Code 45 CFR Part 164 Subpart C\n- Federal Financial Institutions Examination Council (FFIEC) Cybersecurity Assessment Tool (CAT)\n- North American Electric Reliability Corporation (NERC) Critical Infrastructure Protection (CIP) Standard\n- New Zealand Information Security Manual Version 3.5\n- New York Department of Financial Services (NYDFS) Series 23 NYCRR Part 500; AKA NYDFS500\n- Critical Risk Institue (CRI) Critical Risk Profile Version 1.2\n- European Central Bank (ECB) Cyber Resilience Oversight Expectations (CROEs)\n- Equifax Security Controls Framework Version 1.0\n- Payment Card Industry (PCI) Data Security Standard (DSS) Version 4.0\n- MITRE ATT\u0026CK Enterprise Framework\n- CIS AWS Database Services Benchmark V1.0\n- CIS Amazon Web Services Foundations Benchmark V1.5\n- CIS Amazon Web Services Foundations Benchmark V2.0\n- CIS Amazon Web Services Foundations Benchmark V3.0\n- CIS Microsoft Azure Foundations Benchmark V2.0.0\n\n## Repository Security\n\nSince ElectricEye is a security tool, it only makes sense to ensure a high-level of security of components are maintained. To that end the following tools are configured for usage. Refer to the build badges and Actions for detailed information about each run.\n\n#### [`Syft`](https://github.com/anchore/syft)\n\nSee [results here](https://github.com/jonrau1/ElectricEye/actions/workflows/sbom-vulns.yml)!\n\nA CLI tool and Go library for generating a Software Bill of Materials (SBOM) from container images and filesystems.\n\nElectricEye uses Syft to build an SBOM off of a built ElectricEye Docker Image in CycloneDX format and upload it as an artifact to every succesful GitHub Action run.\n\n#### [`Grype`](https://github.com/anchore/grype)\n\nSee [results here](https://github.com/jonrau1/ElectricEye/actions/workflows/sbom-vulns.yml)!\n\nA vulnerability scanner for container images and filesystems. Easily install the binary to try it out. Works with Syft, the powerful SBOM (software bill of materials) tool for container images and filesystems.\n\nElectricEye passes the CycloneDX SBOM from `Syft` to `Grype` to perform vulnerability scans on the built Docker image which combines all Python dependencies and built-in methods within the `alpine` Docker Image parent that ElectricEye uses. Builds with critical vulnerabilities are broken automatically. The results are posted to the GitHub Action and uploaded as `sarif` to GitHub Security\n\n#### [`Dependabot`](https://github.com/dependabot)\n\nDependabot alerts tell you that your code depends on a package that is insecure. If your code depends on a package with a security vulnerability, this can cause a range of problems for your project or the people who use it. You should upgrade to a secure version of the package as soon as possible. If your code uses malware, you need to replace the package with a secure alternative.\n\nElectricEye uses Dependabot as a Software Composition Analysis (SCA) tool to run daily scans and open Pull Requests in the event that a Docker, Python, or GitHub-Action dependency requires a security patch.\n\n#### [`CodeQL`](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql)\n\nSee [results here](https://github.com/jonrau1/ElectricEye/actions/workflows/codeql-analysis.yml)!\n\nCodeQL is the code analysis engine developed by GitHub to automate security checks. You can analyze your code using CodeQL and display the results as code scanning alerts.\n\nElectricEye uses `codeql` as a Static Application Security Testing (SAST) tool to scan all Auditors which are written in Python, `codeql` also looks for secrets in code. It is ran on push and on a schedule.\n\n## License\n\nThis library is licensed under the Apache-2.0 License. See the LICENSE file.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonrau1%2FElectricEye","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonrau1%2FElectricEye","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonrau1%2FElectricEye/lists"}