From f77d44668240591c29cd35b7ce5b369382734cf7 Mon Sep 17 00:00:00 2001 From: Gabriel Soltz <8935378+gabrielsoltz@users.noreply.github.com> Date: Sun, 17 Dec 2023 16:22:15 +0100 Subject: [PATCH] Documentation and Code Improvements (#78) * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * README * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * readme * docs --- README.md | 1026 +++++++++++++++++++++++++++++----------- docs/context.md | 225 ++++----- docs/imgs/impact.png | Bin 0 -> 67019 bytes lib/actions.py | 97 ++++ lib/config/impact.yaml | 21 +- lib/findings.py | 86 +--- lib/helpers.py | 213 ++++++--- lib/impact/impact.py | 26 +- lib/main.py | 361 +++----------- lib/outputs.py | 592 +++++++++++++---------- lib/securityhub.py | 12 + 11 files changed, 1546 insertions(+), 1113 deletions(-) create mode 100644 docs/imgs/impact.png create mode 100644 lib/actions.py diff --git a/README.md b/README.md index b0652a3..467069d 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,11 @@ # Table of Contents - [Description](#description) +- [Quick Run](#quick-run) - [Context](#context) - [Impact](#impact) -- [Architecture](#architecture) +- [High Level Architecture](#high-level-architecture) - [Use Cases](#use-cases) -- [Features](#features) - [Configuration](#customizing-configuration) - [Run with Python](#run-with-python) - [Run with Docker](#run-with-docker) @@ -27,67 +27,383 @@ - [Configuring Security Hub](#configuring-security-hub) - [Configuring Context](#configuring-context) - [Inputs](#Inputs) -- [Output Modes](#output-modes) +- [Output](#outputs) - [Filters](#filters) -- [Updating Workflow Status](#updating-workflow-status) -- [Enriching Findings](#enriching-findings) -- [Findings Aggregation](#findings-aggregation) +- [Security Hub Actions](#security-hub-actions) +- [Contributing](#contributing) # Description -**MetaHub** is an open-source security tool for **impact-contextual vulnerability management**. It can automate the process of **contextualizing** security findings based on your environment and your needs: YOUR **context**, identifying **ownership**, and calculate an **impact scoring** based on it that you can use for defining prioritization and automation. You can use it with [AWS Security Hub](https://aws.amazon.com/security-hub) or any [ASFF](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.html) security scanners (like [Prowler](https://github.com/prowler-cloud/prowler)). +**MetaHub** is an open-source security tool for **impact-contextual vulnerability management**. It can automate the process of **contextualizing** security findings based on your environment and your needs, YOUR **context**, identifying **ownership**, and calculate an **impact scoring** based on it that you can use for defining prioritization (where should you start?) and automations like remediations, alerts or tickets. The tool is for AWS environments and you can use it with [AWS Security Hub](https://aws.amazon.com/security-hub) or any [ASFF](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-findings-format.html) compatible scanners (like [Prowler](https://github.com/prowler-cloud/prowler)). -**MetaHub** describe your context by connecting to your affected resources in your affected accounts. It can describe information about your AWS account and organization, the affected resources tags, the affected CloudTrail events, your affected resource configurations, and all their associations: if you are contextualizing a security finding affecting an EC2 Instance, MetaHub will not only connect to that instance itself but also its IAM Roles; from there, it will connect to the IAM Policies associated with those roles. It will connect to the Security Groups and analyze all their rules, the VPC and the Subnets where the instance is running, the Volumes, the Auto Scaling Groups, and more. +**MetaHub** describes your [**context**](#context) by connecting to your affected resources in your affected accounts. It can describe information about your AWS account and organization, the affected resources tags, related CloudTrail events, your affected resource configurations **and all their associations**: if you are contextualizing a security finding affecting an EC2 Instance, **MetaHub** will not only connect to that instance itself but also its IAM Roles; from there, it will connect to the IAM Policies associated with those roles. It will connect to the Security Groups and analyze all their rules, the VPC and the Subnets where the instance is running, the Volumes, the Auto Scaling Groups, and more. You can apply [**filters**](#filters) to automate detecting other resources with the same properties and do in-depth investigations. -After fetching all the information from your context, **MetaHub** will evaluate certain important conditions for all your resources: `exposure`, `access`, `encryption`, `status`, `environment`, `application` and `owner`. Based on those calculations and in addition to the information from the security findings affecting the resource all together, MetaHub will generate a **Scoring** for each finding. +After fetching all the information from your **context**, **MetaHub** will evaluate the [**impact**](#impact) conditions for all your resources: [**exposure**](#exposure), [**access**](#access), [**encryption**](#encryption), [**status**](#status), [**environment**](#environment), [**application**](#application), and [**owner**](#owner) and based on those calculations and in addition to the information about the security [**findings**](#findings) affecting the resource all **together**, **MetaHub** will generate a **score** for each finding and affected resource. -Check the following dashboard generated by MetaHub. You have the affected resources, grouping all the security findings affecting them together and the original severity of the finding. After that, you have the **Impact Score** and all the criteria MetaHub evaluated to generate that score. All this information is filterable, sortable, groupable, downloadable, and customizable. +Check the following dashboard generated by **MetaHub**. You have the affected resources, grouping all the security findings affecting them together and the original severity of each finding. After that, you have the **score** and all the criteria **MetaHub** evaluated to generate that **score**. All this information is filterable, sortable, groupable, downloadable, and customizable. -You can rely on this **Impact Score** for prioritizing findings (where should you start?), directing attention to critical issues, and automating alerts and escalations. - -**MetaHub** can also filter, deduplicate, group, report, suppress, or update your security findings in automated workflows. It is designed for use as a CLI tool or within automated workflows, such as AWS Security Hub custom actions or AWS Lambda functions. - -The following is the JSON output for a an EC2 instance; see how MetaHub organizes all the information about its context together, under `associations`, `config`, `tags`, `account` `cloudtrail`, and `impact` +The following is the JSON [output](#outputs) for an EC2 instance; see how **MetaHub** organizes all the information about its **context** together, under [**associations**](#associations), [**config**](#config), [**tags**](#tags), [**account**](#account) and [**cloudtrail**](#cloudtrail), and finally the [**impact**](#impact) key with the **score** and all the criteria evaluated to generate that **score**.

Diagram

-# Context +**MetaHub** provides a range of ways to list, manage, and output your security findings for investigation, suppression, updating, and integration with other tools. It is designed for use as a [CLI](#run-with-python) tool or within automated workflows, such as [AWS Lambda functions](#run-with-lambda). It supports different **[outputs](#outputs)**, some of them [**programatic json**](#json), but also powerful [**html**](#html), [**xlsx**](#xlsx) and [**csv**](#csv) that you can [customize](#customize-html-csv-or-xlsx-outputs). + +If you use **AWS Security Hub**, MetaHub integrates smoothly and extends its functionalities. It can be used as a **[Security Hub Custom Action](#run-with-security-hub-custom-action)**, it supports **[AWS Security Hub filters](security-hub-filtering)**, you can manage the **[workflow status of your findings](#updating-workflow-status)**, and you can even **[enrich your findings directly in AWS Security Hub](#enriching-findings)**. + +**MetaHub** is designed to be used with AWS and supports **multi-account setups**. You can run the tool from any environment by assuming roles in your AWS Security Hub `master` and your `child/service` accounts. This allows you to fetch aggregated data from multiple accounts using your AWS Security Hub multi-account implementation while also fetching and enriching those findings with data from the accounts where your affected resources are running. Refer to [Configuring Security Hub](#configuring-security-hub) for more information. + +# Quick Run + +Read your security findings from AWS Security Hub with the default filters and executes the default context options: + +```bash +./metahub +``` -In **MetaHub**, context refers to information about the affected resources like their configuration, associations, logs, tags, account, and more. +Read your security findings from Prowler as an input file and executes the default context options: -MetaHub doesn't stop at the affected resource but analyzes any associated or attached resources. For instance, if there is a security finding on an EC2 instance, MetaHub will not only analyze the instance but also the security groups attached to it, including their rules. MetaHub will examine the IAM roles that the affected resource is using and the policies attached to those roles for any issues. It will analyze the EBS attached to the instance and determine if they are encrypted. It will also analyze the Auto Scaling Groups that the instance is associated with and how. MetaHub will also analyze the VPC, Subnets, and other resources associated with the instance. +```bash +python3 prowler.py aws -M json-asff -q +./metahub --inputs file-asff --input-asff /path/to/prowler-findings.json.asff +``` + +Read a specific (filtered by Id) security finding from AWS Security Hub and executes the default context options: -The **Context** module has the capability to retrieve information from the affected resources, affected accounts, and every associated resources. The context module has five main parts: `config` (which includes `associations` as well), `tags`, `cloudtrail`, and `account`. By default `config`, `tags` and `account` are enabled, but you can change this behavior using the option `--context` (for enabling all the context modules you can use `--context config tags cloudtrail account`). The output of each enabled key will be added under the affected resource. +```bash +./metahub --sh-filters Id=arn:aws:securityhub:us-east-1:123456789012:security-control/CloudFront.1/finding/8bd4d049-dcbc-445b-a5d1-595d8274b4c1 +``` -- [Config](#config) -- [Associations](#associations) -- [Tags](#tags) -- [CloudTrail](#cloudtrail) -- [Account](#account) +Read all the security findings affecting one resource which are ACTIVE (filtered by ResourceId and RecordState) from AWS Security Hub and executes the default context options: + +```bash +./metahub --sh-filters RecordState=ACTIVE ResourceId=arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-0b7d243ff90ebc03e +``` + +Read all the security findings affecting an AWS Account which are ACTIVE (filtered by AwsAccountId and RecordState) for resources with a tag `Environment` and the value `stg` and executes the context options `config` and `tags`: + +```bash +./metahub --sh-filters RecordState=ACTIVE AwsAccountId=123456789012 --mh-filters-tags Environment=stg --context config tags +``` + +# Context + +In **MetaHub**, **context** refers to information about the affected resources like their **configuration**, **associations**, **logs**, **tags** and **account**. + +MetaHub doesn't stop at the affected resource but also analyzes any associated or attached resources. For instance, if a security finding exists on a Security Group, **MetaHub** will analyze the Security Group and everything else associated with it, like the EC2 instances using it. For each associated resource, **MetaHub** will fetch its context. If the Security Group is attached to an EC2 Instance, **MetaHub** will analyze the instance and all its associations, like the IAM Roles and policies. From a single security finding on a Security Group, **MetaHub** will fetch the context of the Security Group, the EC2 Instance, the IAM Roles, and the IAM Policies. This is critical for understanding the impact of your security findings. + +The **context** module has five main parts: [**config**](#config) (which includes [**associations**](#associations)), [**tags**](#tags), [**cloudtrail**](#cloudtrail), and [**account**](#account). By default only **config**, **tags** and **account** are enabled, but you can change this behavior using the option `--context` (e.g. use `--context config tags cloudtrail account` for enabling all context keys, or `--context config` for enabling only the config and associations key.): ## Config -Under the `config` key, you can find anyting related to the configuration of the affected resource. For example, if the affected resource is an EC2 Instance, you will see keys like `private_ip`, `public_ip`, or `instance_profile`. +Under the `config` key, you can find important configuration from the affected resource. For example, if the affected resource is an S3 Bucket, you will find information about its bucket policy, its ACLs, its encryption configuration, and more. If the affected resource is an EC2 Instance, you will find information about its key, its public and private IP, its metadata and more. The configuration information that **MetaHub** fetches is defined by resource type. If you want to add more configuration information see [contributing](#contributing). -You can filter your findings based on Config outputs using the option: `--mh-filters-config {True/False}`. See [Config Filters](#config-filters). +You can filter your findings based on config outputs using the option: `--mh-filters-config {True/False}` (see [config filters](#config-filters)). + +
+ Example for an S3 bucket config key + +```json +"config": { + "resource_policy": { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "Test", + "Effect": "Allow", + "Principal": { + "Service": "config.amazonaws.com" + }, + "Action": "s3:GetBucketAcl", + "Resource": "arn:aws:s3:::metahub-bucket", + "Condition": { + "StringEquals": { + "AWS:SourceAccount": "123456789012" + } + } + }, + ] + }, + "website_enabled": false, + "bucket_acl": [ + { + "Grantee": { + "DisplayName": "gabriel.soltz", + "ID": "1234564bd76c6c64080717b68eafaa588b41706daaf22d3d0705b398bd7cbd57", + "Type": "CanonicalUser" + }, + "Permission": "FULL_CONTROL" + } + ], + "cannonical_user_id": "1234564bd76c6c64080717b68eafaa588b41706daaf22d3d0705b398bd7cbd57", + "public_access_block_enabled": { + "BlockPublicAcls": true, + "IgnorePublicAcls": true, + "BlockPublicPolicy": true, + "RestrictPublicBuckets": true + }, + "account_public_access_block_enabled": false, + "public": false, + "bucket_encryption": [ + { + "ApplyServerSideEncryptionByDefault": { + "SSEAlgorithm": "AES256" + }, + "BucketKeyEnabled": false + } + ] +}, +``` + +
## Associations -Under the `associations` key, you will find all the associated resources of the affected resource. For example, if the affected resource is an EC2 Instance, you will find resources like: Security Groups, IAM Roles, Volumes, VPC, Subnets, Auto Scaling Groups, etc. Each time MetaHub finds an association, it will connect to the associated resource again and fetch its own context. +Under the `associations` key, you will find all the associated resources of the affected resource. For example, if the affected resource is an EC2 Instance, you will find resources like: Security Groups, IAM Roles, Volumes, VPC, Subnets, Auto Scaling Groups. If the affected resource is a IAM Role, you will find resources like IAM Policies, IAM Users, IAM Groups, and more. Each time MetaHub finds an association, it will connect to the associated resource again and fetch its own context. Associations are key to understanding the context and impact of your security findings. -Associations are key to understanding the context and impact of your security findings as their exposure. +You can filter your findings based on associations outputs using the option: `--mh-filters-config {True/False}` (see [config filters](#config-filters)). -You can filter your findings based on Associations outputs using the option: `--mh-filters-config {True/False}`. See [Config Filters](#config-filters). +
+ Example for an EC2 instance assocations key + +```json +"associations": { + "security_groups": { + "arn:aws:ec2:eu-west-1:123456789012:security-group/sg-020cc749a58678e05": { + "associations": { + "vpcs": { + "arn:aws:ec2:eu-west-1:123456789012:vpc/vpc-03cc56a1c2afb5760": { + "associations": { + "subnets": { + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-03d86f1ccd7729d85": {}, + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-0ccfb8dea658f49ec": {}, + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-05e85a7b0ec9e404c": {}, + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-0e177ea95bcc76256": {} + } + }, + "config": { + "cidr": "172.10.0.0/16", + "default": false, + "public": null + } + } + }, + "network_interfaces": { + "arn:aws:ec2:eu-west-1:123456789012:network-interface/eni-041a6e5bb59c336ee": {} + }, + "instances": { + "arn:aws:ec2:eu-west-1:123456789012:instance/i-018daeedcf06398c0": {} + } + }, + "config": { + "public_ips": [ + "100.100.100.100" + ], + "managed_services": [], + "its_referenced_by_a_security_group": false, + "security_group_rules": [ + { + "SecurityGroupRuleId": "sgr-08cdc9fdac8fd1a5b", + "GroupId": "sg-020cc749a58678e05", + "GroupOwnerId": "123456789012", + "IsEgress": true, + "IpProtocol": "-1", + "FromPort": -1, + "ToPort": -1, + "CidrIpv4": "0.0.0.0/0", + "Tags": [] + }, + { + "SecurityGroupRuleId": "sgr-0e6cd39169dc137ab", + "GroupId": "sg-020cc749a58678e05", + "GroupOwnerId": "123456789012", + "IsEgress": false, + "IpProtocol": "tcp", + "FromPort": 22, + "ToPort": 22, + "CidrIpv4": "0.0.0.0/0", + "Tags": [] + } + ], + "public": true, + "default": false, + "attached": true, + "resource_policy": null + } + }, + }, + "iam_roles": { + "arn:aws:iam::123456789012:role/eu-west-1-stg-backend-iam-role": { + "associations": { + "iam_policies": { + "arn:aws:iam::123456789012:policy/eu-west-1-stg-backend-iam-policy-cw": { + "associations": { + "iam_roles": { + "arn:aws:iam::123456789012:role/eu-west-1-stg-backend-iam-role": {} + }, + "iam_groups": {}, + "iam_users": {} + }, + "config": { + "name": "eu-west-1-stg-backend-iam-policy-cw", + "description": false, + "customer_managed": true, + "attached": true, + "public": null, + "resource_policy": { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "logs:CreateLogGroup", + "logs:CreateLogStream", + "logs:PutLogEvents", + "logs:DescribeLogStreams" + ], + "Resource": [ + "arn:aws:logs:*:*:*" + ] + } + ] + } + } + }, + } + }, + "config": { + "iam_inline_policies": {}, + "instance_profile": "arn:aws:iam::123456789012:instance-profile/eu-west-1-stg-backend-iam-profile", + "trust_policy": { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "", + "Effect": "Allow", + "Principal": { + "Service": "ec2.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] + }, + "permissions_boundary": false, + "public": null, + "resource_policy": null + } + } + }, + "volumes": { + "arn:aws:ec2:eu-west-1:123456789012:volume/vol-0371a09e338f582da": { + "associations": { + "instances": { + "arn:aws:ec2:eu-west-1:123456789012:instance/i-018daeedcf06398c0": {} + } + }, + "config": { + "encrypted": true, + "attached": true, + "public": null, + "resource_policy": null + } + } + }, + "autoscaling_groups": { + "arn:aws:autoscaling:eu-west-1:123456789012:autoScalingGroup/stg-backend-20201205160228428400000002": { + "associations": { + "instances": { + "arn:aws:ec2:eu-west-1:123456789012:instance/i-018daeedcf06398c0": {} + }, + "launch_templates": { + "arn:aws:ec2:eu-west-1:123456789012:launch-template/lt-06b73d2e77f10446f": {} + }, + "launch_configurations": {} + }, + "config": { + "name": "stg-backend-20201205160228428400000002", + "public": null, + "resource_policy": null + } + } + }, + "vpcs": { + "arn:aws:ec2:eu-west-1:123456789012:vpc/vpc-03cc56a1c2afb5760": { + "associations": { + "subnets": { + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-03d86f1ccd7729d85": {}, + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-0ccfb8dea658f49ec": {}, + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-05e85a7b0ec9e404c": {}, + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-0e177ea95bcc76256": {} + } + }, + "config": { + "cidr": "172.10.0.0/16", + "default": false, + "public": null + } + } + }, + "subnets": { + "arn:aws:ec2:eu-west-1:123456789012:subnet/subnet-03d86f1ccd7729d85": { + "associations": { + "route_tables": { + "arn:aws:ec2:eu-west-1:123456789012:route-table/rtb-0ebae6462f919943d": { + "associations": {}, + "config": { + "default": false, + "route_to_internet_gateway": [ + { + "DestinationCidrBlock": "0.0.0.0/0", + "GatewayId": "igw-0790540d8d726f9d4", + "Origin": "CreateRoute", + "State": "active" + } + ], + "route_to_nat_gateway": [], + "route_to_transit_gateway": [], + "route_to_vpc_peering": [], + "public": null + } + } + }, + "network_interfaces": { + "arn:aws:ec2:eu-west-1:123456789012:network-interface/eni-0e8918fa31d2acd55": {}, + "arn:aws:ec2:eu-west-1:123456789012:network-interface/eni-0f6c936934fd9d6a6": {}, + "arn:aws:ec2:eu-west-1:123456789012:network-interface/eni-041a6e5bb59c336ee": {}, + "arn:aws:ec2:eu-west-1:123456789012:network-interface/eni-0e5f6cfdc7c286224": {} + }, + "instances": { + "arn:aws:ec2:eu-west-1:123456789012:instance/i-018daeedcf06398c0": {} + } + }, + "config": { + "cidr": "172.11.11.0/24", + "map_public_ip_on_launch_enabled": true, + "default": false, + "public": true, + "resource_policy": null, + "public_ips": [ + "100.100.100.100", + ], + "managed_services": [ + "ELB app/stg-alb-backend/3567d780bd062d75", + "Interface for NAT Gateway nat-0805d9808347bba69" + ], + "attached": true + } + } + }, +} +``` -## Tags +
-**MetaHub** relies on [AWS Resource Groups Tagging API](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/overview.html) to query the tags associated with your resources. +## Tags -Note that not all AWS resource type supports this API. You can check [supported services](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/supported-services.html). +Under the `tags` key, you will find all the tags associated with the affected resource. **MetaHub** relies on [AWS Resource Groups Tagging API](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/overview.html) to query the tags associated with your resources. Note that not all AWS resource type supports this API. You can check [supported services](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/supported-services.html). Tags are a crucial part of understanding your context. Tagging strategies often include: @@ -98,37 +414,111 @@ Tags are a crucial part of understanding your context. Tagging strategies often If you follow a proper tagging strategy, you can filter and generate interesting outputs. For example, you could list all findings related to a specific team and provide that data directly to that team. -You can filter your findings based on Tags outputs using the option: `--mh-filters-tags TAG=VALUE`. See [Tags Filtering](#tags-filtering) +You can filter your findings based on tags outputs using the option: `--mh-filters-tags TAG=VALUE` (see [tags filters](#tags-filters)). + +
+ Example for an EC2 instance tag key + +```json +"tags": { + "aws:autoscaling:groupName": "stg-backend-20201205160228428400000002", + "environment": "stg", + "terraform": "true", + "aws:ec2launchtemplate:version": "8", + "aws:ec2launchtemplate:id": "lt-06b73d2e77f10446f", + "Name": "stg-backend" +} +``` + +
## CloudTrail -Under the key `cloudtrail`, you will find critical Cloudtrail events related to the affected resource, such as creating events. +Under the key `cloudtrail`, you will find critical Cloudtrail events related to the affected resource, such as creation events. The Cloudtrail events we look for are defined by resource type, and you can add, remove, or change them by editing the configuration file [resources.py](lib/config/resources.py). For example, for an affected resource of type Security Group, MetaHub will look for the following events: `CreateSecurityGroup` (Security Group Creation event) and `AuthorizeSecurityGroupIngress` (Security Group Rule Authorization event). + +
+ Example for an EC2 instance cloudtrail key + +```json +"cloudtrail": { + "RunInstances": { + "Username": "root", + "EventTime": "2023-11-15 06:10:07+01:00", + "EventId": "4f122d76-812d-4438-bc33-3585a9e863cf" + } +} +``` -The Cloudtrail events that we look for are defined by resource type, and you can add, remove or change them by editing the configuration file [resources.py](lib/config/resources.py). +
-For example for an affected resource of type Security Group, MetaHub will look for the following events: +
+ Example for a DynamoDB table cloudtrail key + +```json +"cloudtrail": { + "CreateTable": { + "Username": "gabriel.soltz", + "EventTime": "2023-12-05 14:34:25+01:00", + "EventId": "7110e3ae-09a3-44b9-929a-1775e0fbedcf" + } +} +``` -- `CreateSecurityGroup`: Security Group Creation event -- `AuthorizeSecurityGroupIngress`: Security Group Rule Authorization event. +
## Account -Under the key `account`, you will find information about the account where the affected resource is runnning, like if it's part of an AWS Organizations, information about their contacts, etc. +Under the key `account`, you will find information about the account where the affected resource is runnning, like if it's part of an AWS Organizations, information about their contacts, and more. -# Impact + + +
+ Example for account key + +```json +"account": { + "Alias": "metahub-demo", + "AlternateContact": { + "AlternateContactType": "SECURITY", + "EmailAddress": "gabriel@domain.com", + "Name": "Gabriel", + "PhoneNumber": "+1234567890", + "Title": "Security" + }, + "Organizations": { + "Arn": "arn:aws:organizations::123456789012:organization/o-12349772jb", + "Id": "o-12349772jb", + "MasterAccountId": "123456789012", + "MasterAccountEmail": "gabriel.soltz@domain.com", + "FeatureSet": "ALL", + "DelegatedAdministrators": {}, + "Details": { + "ParentId": "r-k123", + "ParentType": "ROOT", + "OU": "ROOT", + "Policies": { + "p-FullAWSAccess": { + "Name": "FullAWSAccess", + "Arn": "arn:aws:organizations::aws:policy/service_control_policy/p-FullAWSAccess", + "Type": "SERVICE_CONTROL_POLICY", + "Description": "Allows access to every operation", + "AwsManaged": true, + "Targets": [] + } + } + } + } +}, +``` -The impact module in MetaHub focuses on generating a score for each finding based on the context of the affected resource and all the security findings affecting them and their severities together. The impact score is a number between 0 and 100, where 100 is the highest impact. +
+ +# Impact -The formula for getting the impact score include the following criteria: + -- [Exposure](#exposure) -- [Access](#access) -- [Encryption](#encryption) -- [Status](#status) -- [Environment](#environment) -- [Application](#application) -- [Owner](#owner) -- [Findings](#findings) +The impact module in MetaHub focuses on understanding the 7 key properties of the affected resource: [**exposure**](#exposure), [**access**](#access), [**encryption**](#encryption), [**status**](#status), [**environment**](#environment), [**application**](#application), and [**owner**](#owner) and combining their values with the values of all the security [findings](#findings) affecting the same resource and their severities to generate a **score**. The impact score is a number between 0 and 100, where 100 is the highest impact. +


## Exposure @@ -143,6 +533,46 @@ The formula for getting the impact score include the following criteria: | 🟢 restricted | 0% | The resource is restricted. | | 🔵 unknown | - | The resource couldn't be checked | +
+ Example for an effectively-public resource + +```json +"exposure": { --> The exposure key + "effectively-public": { --> The exposure value, effectively-public + "entrypoint": "66.66.66.66", --> The entrypoint to the resource from the Internet (Ip, Domain, etc.) + "unrestricted_ingress_rules": [ --> The unrestricted ingress rules, if any + { + "SecurityGroupRuleId": "sgr-0553206714e321b87", + "GroupId": "sg-0a15a46e47f07d139", + "GroupOwnerId": "123456789012", + "IsEgress": false, + "IpProtocol": "tcp", + "FromPort": 22, + "ToPort": 22, + "CidrIpv4": "0.0.0.0/0", + "Tags": [] + } + ], + "unrestricted_egress_rules": [ --> The unrestricted egress rules, if any + { + "SecurityGroupRuleId": "sgr-007b509667896ebe3", + "GroupId": "sg-0a15a46e47f07d139", + "GroupOwnerId": "123456789012", + "IsEgress": true, + "IpProtocol": "-1", + "FromPort": -1, + "ToPort": -1, + "CidrIpv4": "0.0.0.0/0", + "Tags": [] + }, + ], + "resource_public_config": true --> The public configuration of the resource + } +} +``` + +
+ ## Access **Access** evaluates the resource policy layer. MetaHub checks every available policy including: IAM Managed policies, IAM Inline policies, Resource Policies, Bucket ACLS, and any association to other resources like IAM Roles which its policies are also analyzed . An unrestricted policy is not only an itsue itself of that policy, it afected any other resource which is using it. @@ -159,6 +589,30 @@ The formula for getting the impact score include the following criteria: | 🟢 restricted | 0% | The policy is restricted. | | 🔵 unknown | - | The policy couldn't be checked. | +
+ Example for an unrestricted-actions resource + +```json +"access": { --> The access key + "unrestricted-actions": { --> The access value, unrestricted-actions + "wildcard_actions": { --> The wildcard policies, if any + "arn:aws:iam::123456789012:policy/eu-west-1-stg-iam-policy-dynamodb-cache": [ + { + "Action": [ + "dynamodb:*" --> The wildcard action + ], + "Effect": "Allow", + "Resource": [ + "arn:aws:dynamodb:eu-west-1:123456789012:table/table", + ] + } + ], + } +} +``` + +
+ ## Encryption **Encryption** evaluate the different encryption layers based on each resource type. For example, for some resources it evaluates if `at_rest` and `in_transit` encryption configuration are both enabled. @@ -169,6 +623,22 @@ The formula for getting the impact score include the following criteria: | 🟢 encrypted | 0% | The resource is fully encrypted including any of it's associations. | | 🔵 unknown | - | The resource encryption couldn't be checked. | +
+ Example for an unencrypted resource + +```json +"encryption": { --> The encryption key + "unencrypted": { --> The encryption value, unencrypted + "unencrypted_resources": [ --> the unencrypted resources associated with the affected resource, if any + "arn:aws:ec2:eu-west-1:012345678901:volume/vol-0ac713ec808a8d8bd" + ], + "resource_encryption_config": null --> The encryption configuration of the resource, if it has any + } +} +``` + +
+ ## Status **Status** evaluate the status of the affected resource in terms of attachment or functioning. For example, for an EC2 Instance we evaluate if the resource is running, stopped, or terminated, but for resources like EBS Volumes and Security Groups, we evaluate if those resources are attached to any other resource. @@ -183,6 +653,20 @@ The formula for getting the impact score include the following criteria: | 🟢 not-enabled | 0% | The resource supports enabled and it is not enabled. | | 🔵 unknown | - | The resource couldn't be checked for status. | +
+ Example for a running resource + +```json +"status": { --> The status key + "running": { --> The status value, running + "status": "running", --> The status configuration of the resource, if it has any + "attached": null --> The attachment configuration of the resource, if it has any + } +} +``` + +
+ ## Environment **Environment** evaluates the environment where the affected resource is running. By default, MetaHub defines 3 environments: `production`, `staging`, and `development`, but you can add, remove, or modify these environments based on your needs. MetaHub evaluates the environment based on the tags of the affected resource, the account id or the account alias. You can define your own environemnts definitions and strategy in the configuration file (See [Customizing Configuration](#customizing-configuration)). @@ -194,6 +678,21 @@ The formula for getting the impact score include the following criteria: | 🟢 development | 0% | It is a development resource. | | 🔵 unknown | - | The resource couldn't be checked for enviroment. | +
+ Example for a production resource matched by Tags + +```json +"environment": { --> The environment key + "production": { --> The environment value, production + "tags": { --> The parameters used for evaluating the environment, in this case tags + "Env": "prod" --> The tag and key found used for evaluating the environment + } + } +} +``` + +
+ ## Application **Application** evaluates the application that the affected resource is part of. MetaHub relies on the AWS [myApplications](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/aws-myApplications.html) feature, which relies on the Tag `awsApplication`, but you can extend this functionality based on your context for example by defining other tags you use for defining applications or services (like `Service` or any other), or by relying on account id or alias. You can define your application definitions and strategy in the configuration file (See [Customizing Configuration](#customizing-configuration)). @@ -202,6 +701,21 @@ The formula for getting the impact score include the following criteria: | --------------------- | :-------: | ------------------------------------------------- | | 🔵 unknown | - | The resource couldn't be checked for application. | +
+ Example for a resource matched by myApplication Tag + +```json +"application": { --> The application key + "payments-app": { --> The application value, payments-app + "tags": { --> The parameters used for evaluating the environment, in this case the tag awsApplication + "awsApplication": "arn:aws:resource-groups:eu-west-1:123456789012:group/app1/0c8vpbjkzeeffsz2cqgxpae7b2" --> The tag and key found used for evaluating the environment + } + } +} +``` + +
+ ## Owner **Owner** focuses on ownership detection. It can determine the owner of the affected resource in various ways. This information can be used to automatically assign a security finding to the correct owner, escalate it, or make decisions based on this information. An automated way to determine the owner of a resource is critical for security teams. It allows them to focus on the most critical issues and assign them as fast as possible to the right people in automated workflows. You can define your owner definitions and strategy in the configuration file (See [Customizing Configuration](#customizing-configuration)). @@ -210,6 +724,22 @@ The formula for getting the impact score include the following criteria: | --------------------- | :-------: | ------------------------------------------- | | 🔵 unknown | - | The resource couldn't be checked for owner. | +
+ Example for a resource matched by Account Id + +```json +"owner": { --> The owner key + "payments-team": { --> The owner value, payments-app + "account": { --> The parameters used for evaluating the environment, in this case the account + "account_ids": ["123456789012"], --> The account ids found used for evaluating the environment + "account_aliases": [], + }, + } +} +``` + +
+ ## Findings As part of the impact score calculation, we also evaluate the total ammount of security findings and their severities affecting the resource. We use the following formula to calculate this metric: @@ -242,30 +772,6 @@ Some use cases for MetaHub include: - Created enriched HTML reports for your findings that you can filter, sort, group, and download - Create Security Hub Insights based on MetaHub context -# Features - -**MetaHub** provides a range of ways to list and manage security findings for investigation, suppression, updating, and integration with other tools or alerting systems. To avoid _Shadowing_ and _Duplication_, MetaHub organizes related findings together when they pertain to the same resource. For more information, refer to [Findings Aggregation](#findings-aggregation) - -**MetaHub** queries the affected resources directly in the affected account to provide additional **context** using the following options: - -- **[Config](#Config)**: Fetches the most important configuration values from the affected resource. -- **[Associations](#Associations)**: Fetches all the associations of the affected resource, such as IAM roles, security groups, and more. -- **[Tags](#Tags)**: Queries tagging from affected resources -- **[CloudTrail](#CloudTrail)**: Queries CloudTrail in the affected account to identify who created the resource and when, as well as any other related critical events -- **[Account](#Account)**: Fetches extra information from the account where the affected resource is running, such as the account name, security contacts, and other information. - -**MetaHub** supports filters on top of these context\* outputs to automate the detection of other resources with the same issues. You can filter security findings affecting resources tagged in a certain way (e.g., `Environment=production`) and combine this with filters based on Config or Associations, like, for example, if the resource is public, if it is encrypted, only if they are part of a VPC, if they are using a specific IAM role, and more. For more information, refer to **[Config filters](#config-filters)** and **[Tags filters](#tags-filters)** for more information. - -But that's not all. If you are using **MetaHub** with Security Hub, you can even combine the previous filters with the Security Hub native filters (**[AWS Security Hub filtering](security-hub-filtering)**). You can filter the same way you would with the AWS CLI utility using the option `--sh-filters`, but in addition, you can save and re-use your filters as YAML files using the option `--sh-template`. - -If you prefer, With **MetaHub**, you can back **[enrich your findings directly in AWS Security Hub](#enriching-findings)** using the option `--enrich-findings`. This action will update your AWS Security Hub findings using the field `UserDefinedFields`. You can then create filters or [Insights](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-insights.html) directly in AWS Security Hub and take advantage of the contextualization added by MetaHub. - -When investigating findings, you may need to update security findings altogether. **MetaHub** also allows you to execute **[bulk updates](#updating-workflow-status)** to AWS Security Hub findings, such as changing Workflow Status using the option `--update-findings`. As an example, you identified that you have hundreds of security findings about public resources. Still, based on the MetaHub context, you know those resources are not effectively public as they are protected by routing and firewalls. You can update all the findings for the output of your MetaHub query with one command. When updating findings using MetaHub, you also update the field `Note` of your finding with a custom text for future reference. - -**MetaHub** supports different **[Output Modes](#output-modes)**, some of them **json based** like **json-inventory**, **json-statistics**, **json-short**, **json-full**, but also powerfull **html**, **xlsx** and **csv**. These outputs are customizable; you can choose which columns to show. For example, you may need a report about your affected resources, adding the tag Owner, Service, and Environment and nothing else. Check the configuration file and define the columns you need. - -**MetaHub** supports **multi-account setups**. You can run the tool from any environment by assuming roles in your AWS Security Hub `master` account and your `child/service` accounts where your resources live. This allows you to fetch aggregated data from multiple accounts using your AWS Security Hub multi-account implementation while also fetching and enriching those findings with data from the accounts where your affected resources live based on your needs. Refer to [Configuring Security Hub](#configuring-security-hub) for more information. - # Customizing Configuration **MetaHub** uses configuration files that let you customize some checks behaviors, default filters, and more. The configuration files are located in [lib/config/](lib/config). @@ -410,7 +916,7 @@ The Security Hub custom action is deployed as part of the Terraform code. See [D # AWS Authentication -- Ensure you have AWS credentials set up on your local machine (or from where you will run MetaHub). +Ensure you have AWS credentials set up on your local machine (or from where you will run MetaHub). For example, you can use `aws configure` option. @@ -495,13 +1001,9 @@ You also can combine AWS Security Hub findings with input ASFF files specifying When using a file as input, you can't use the option `--sh-filters` for filter findings, as this option relies on AWS API for filtering. You can't use the options `--update-findings` or `--enrich-findings` as those findings are not in the AWS Security Hub. If you are reading from both sources at the same time, only the findings from AWS Security Hub will be updated. -# Output Modes +# Outputs -**MetaHub** can generate different programmatic and visual outputs. By default, all output modes are enabled: `json-short`, `json-full`, `json-statistics`, `json-inventory`, `html`, `csv`, and `xlsx`. - -The outputs will be saved in the `outputs/` folder with the execution date. - -If you want only to generate a specific output mode, you can use the option `--output-modes` with the desired output mode. +**MetaHub** can generate different programmatic and visual outputs. By default, all output modes are enabled: `json-short`, `json-full`, `json-statistics`, `json-inventory`, `html`, `csv`, and `xlsx`. If you want only to generate a specific output mode, you can use the option `--output-modes` with the desired output mode. The outputs will be saved in the `outputs/` folder with the execution date. For example, if you only want to generate the output `json-short`, you can use: @@ -515,6 +1017,8 @@ If you want to generate `json-short`, `json-full` and `html` outputs, you can us ./metahub.py --output-modes json-short json-full html ``` +**MetaHub** organizes the security findings affecting the same resource all together under the `findings` key for in an attempt to avoid Shadowing (when two checks refer to the same issue, but one in a more generic way than the other one) and Duplication (when you use more than one scanner and get the same problem from more than one.). You can see this behaviour clear in the outputs `json-short`, `json-full` and `html`. + - [JSON](#json) - [HTML](#html) - [CSV](#csv) @@ -522,96 +1026,186 @@ If you want to generate `json-short`, `json-full` and `html` outputs, you can us ## JSON -### JSON-Short - -Show all findings titles together under each affected resource and the `AwsAccountId`, `Region`, and `ResourceType`: - -``` -"arn:aws:sagemaker:us-east-1:ofuscated:notebook-instance/obfuscated": { - "findings": [ - "SageMaker.2 SageMaker notebook instances should be launched in a custom VPC", - "SageMaker.3 Users should not have root access to SageMaker notebook instances", - "SageMaker.1 Amazon SageMaker notebook instances should not have direct internet access" - ], - "AwsAccountId": "obfuscated", - "Region": "us-east-1", - "ResourceType": "AwsSageMakerNotebookInstance", - "config: {}, - "associations: {}, - "tags: {}, - "cloudtrail: {}, - "account: {} - "impact: {} -}, -``` +> :info: For exploring a JSON output interactively, you can use the tool [fx](https://github.com/antonmedv/fx). ### JSON-Full -Show all findings with all data. Findings are organized by ResourceId (ARN). For each finding, you will also get: `SeverityLabel,` `Workflow,` `RecordState,` `Compliance,` `Id`, and `ProductArn`: +Shows the affected resource using it's ARN as the key and the findings affecting it as a list under the key `findings`. In adittion to the findings, you will also get the following keys: `ResourceType`, `Region`, `AwsAccountId`, `associations`, `config`, `tags`, `account`, `cloudtrail`, and `impact`. -``` -"arn:aws:sagemaker:eu-west-1:ofuscated:notebook-instance/obfuscated": { - "findings": [ +```json +"arn:aws:ec2:eu-west-1:1234567890:instance/i-0a40b2be25dbac0ac": { --> The affected resource ARN + "findings": [ --> The findings affecting the resource { - "SageMaker.3 Users should not have root access to SageMaker notebook instances": { - "SeverityLabel": "HIGH", - "Workflow": { - "Status": "NEW" + "EC2 instances should use Instance Metadata Service Version 2 (IMDSv2)": { --> The finding title + "SeverityLabel": "HIGH", --> The finding severity label + "Workflow":{ --> The finding workflow + "Status": "NEW", }, - "RecordState": "ACTIVE", - "Compliance": { - "Status": "FAILED" + "RecordState": "ACTIVE", --> The finding record state + "Compliance":{ --> The finding compliance + "Status": "FAILED", }, - "Id": "arn:aws:security hub:eu-west-1:ofuscated:subscription/aws-foundational-security-best-practices/v/1.0.0/SageMaker.3/finding/12345-0193-4a97-9ad7-bc7c1730eec6", - "ProductArn": "arn:aws:security hub:eu-west-1::product/aws/security hub" + "Id": "arn:aws:securityhub:eu-west-1:123456789012:security-control/EC2.8/finding/a1d4f19f-453e-4c3c-b486-8443c73e84f1", + "ProductArn": "arn:aws:securityhub:eu-west-1::product/aws/securityhub", } }, - { - "SageMaker.2 SageMaker notebook instances should be launched in a custom VPC": { - "SeverityLabel": "HIGH", - "Workflow": { - "Status": "NEW" - }, - "RecordState": "ACTIVE", - "Compliance": { - "Status": "FAILED" - }, - "Id": "arn:aws:security hub:eu-west-1:ofuscated:subscription/aws-foundational-security-best-practices/v/1.0.0/SageMaker.2/finding/12345-e8e1-4915-9881-965104b0aabf", - "ProductArn": "arn:aws:security hub:eu-west-1::product/aws/security hub" - } + {"EC2 instances should be managed by AWS Systems Manager": {...}}, --> Another finding title + {"EC2 instances should not have a public IPv4 address": {...}} --> Another finding title + ], + "ResourceType": "AwsEc2Instance", --> The affected resource type + "Region": "eu-west-1", --> The affected resource region + "AwsAccountId": "1234567890", --> The affected resource account id + "associations": { --> The associations of the affected resource + "security_groups": {}, --> The security groups associated with the affected resource + "iam_roles": {}, --> The IAM roles associated with the affected resource + "volumes": {}, --> The volumes associated with the affected resource + "autoscaling_groups": {}, --> The autoscaling groups associated with the affected resource + "vpcs": {}, --> The VPCs associated with the affected resource + "subnets": {}, --> The subnets associated with the affected resource + }, + "config": { --> The configuration of the affected resource (based on it's type) + "public_ip": "200.200.200.200", --> The public IP of the affected resource, if any + "private_ip": "10.10.10.10", --> The private IP of the affected resource, if any + "key": "ssh-key", --> The key used for the affected resource, if any + "metadata_options": { --> The metadata options of the affected resource, if any + "State": "applied", + "HttpTokens": "required", + "HttpPutResponseHopLimit": 1, + "HttpEndpoint": "enabled", + "HttpProtocolIpv6": "disabled", + "InstanceMetadataTags": "disabled" }, - { - "SageMaker.1 Amazon SageMaker notebook instances should not have direct internet access": { - "SeverityLabel": "HIGH", - "Workflow": { - "Status": "NEW" - }, - "RecordState": "ACTIVE", - "Compliance": { - "Status": "FAILED" - }, - "Id": "arn:aws:security hub:eu-west-1:ofuscated:subscription/aws-foundational-security-best-practices/v/1.0.0/SageMaker.1/finding/12345-3a21-4016-a8e5-f5173b44e90a", - "ProductArn": "arn:aws:security hub:eu-west-1::product/aws/security hub" + }, + "tags": { --> The tags of the affected resource + "Name": "test", --> The tag key and value + "Env": "prod", + "awsApplication": "arn:aws:resource-groups:eu-west-1:1234567890:group/app1/0c8vpbjkzeeffsz2cqgxpae7b2" + }, + "account": { --> The account of the affected resource + "Alias": "prod", --> The account alias + "AlternateContact": {}, --> The alternate contact of the account, if any + "Organizations": { --> The organization of the account, if any + "Id": "o-1234567890", + "Arn": "arn:aws:organizations::1234567890:organization/o-1234567890/o-1234567890", + "MasterAccountId": "1234567890", + "MasterAccountArn": "arn:aws:organizations::1234567890:account/o-1234567890/1234567890", + "MasterAccountEmail": "", + "Details": { + "ParentId": "p-k1234567890", + "ParentType": "ROOT", + "OU": "ROOT", + "Policies": { --> The policies of the account, if any + "p-FullAWSAccess": {...} --> The policy name and policy + } } + }, + }, + "cloudtrail": { --> The CloudTrail events affecting the affected resource + "RunInstances": { --> The CloudTrail event name + "Username": "test", --> The username of the event, if any + "EventTime": "2021-01-01T00:00:00Z", + "EventId": "12345678-1234-1234-1234-123456789012", } + }, + "impact": { --> The impact of the affected resource + "exposure": {...}, --> The exposure impact + "access": {...}, --> The access impact + "encryption": {...}, --> The encryption impact + "status": {...}, --> The status impact + "environment": {...}, --> The environment impact + "application": {...}, --> The application impact + "owner": {...}, --> The owner impact + "findings": {...}, --> The findings impact + "score": {...} --> The total impact score + } +} +``` + +### JSON-Short + +Shows the affected resource using it's ARN as the key and the findings affecting it as a list under the key `findings`. In adittion to the findings, you will also get the following keys: `ResourceType`, `Region`, `AwsAccountId`, `associations`, `config`, `tags`, `account`, `cloudtrail`, and `impact`. + +```json +"arn:aws:ec2:eu-west-1:1234567890:instance/i-0a40b2be25dbac0ac": { --> The affected resource ARN + "findings": [ --> The findings affecting the resource + "EC2 instances should use Instance Metadata Service Version 2 (IMDSv2)", --> The finding title + "EC2 instances should be managed by AWS Systems Manager", --> The finding title + "EC2 instances should not have a public IPv4 address" --> The finding title ], - "AwsAccountId": "obfuscated", - "Region": "eu-west-1", - "ResourceType": "AwsSageMakerNotebookInstance", - "config: {}, - "associations: {}, - "tags: {}, - "cloudtrail: {}, - "account: {} - "impact: {} -}, + "ResourceType": "AwsEc2Instance", --> The affected resource type + "Region": "eu-west-1", --> The affected resource region + "AwsAccountId": "1234567890", --> The affected resource account id + "associations": { --> The associations of the affected resource + "security_groups": {}, --> The security groups associated with the affected resource + "iam_roles": {}, --> The IAM roles associated with the affected resource + "volumes": {}, --> The volumes associated with the affected resource + "autoscaling_groups": {}, --> The autoscaling groups associated with the affected resource + "vpcs": {}, --> The VPCs associated with the affected resource + "subnets": {}, --> The subnets associated with the affected resource + }, + "config": { --> The configuration of the affected resource (based on it's type) + "public_ip": "200.200.200.200", --> The public IP of the affected resource, if any + "private_ip": "10.10.10.10", --> The private IP of the affected resource, if any + "key": "ssh-key", --> The key used for the affected resource, if any + "metadata_options": { --> The metadata options of the affected resource, if any + "State": "applied", + "HttpTokens": "required", + "HttpPutResponseHopLimit": 1, + "HttpEndpoint": "enabled", + "HttpProtocolIpv6": "disabled", + "InstanceMetadataTags": "disabled" + }, + }, + "tags": { --> The tags of the affected resource + "Name": "test", --> The tag key and value + "Env": "prod", + "awsApplication": "arn:aws:resource-groups:eu-west-1:1234567890:group/app1/0c8vpbjkzeeffsz2cqgxpae7b2" + }, + "account": { --> The account of the affected resource + "Alias": "prod", --> The account alias + "AlternateContact": {}, --> The alternate contact of the account, if any + "Organizations": { --> The organization of the account, if any + "Id": "o-1234567890", + "Arn": "arn:aws:organizations::1234567890:organization/o-1234567890/o-1234567890", + "MasterAccountId": "1234567890", + "MasterAccountArn": "arn:aws:organizations::1234567890:account/o-1234567890/1234567890", + "MasterAccountEmail": "", + "Details": { + "ParentId": "p-k1234567890", + "ParentType": "ROOT", + "OU": "ROOT", + "Policies": { --> The policies of the account, if any + "p-FullAWSAccess": {...} --> The policy name and policy + } + } + }, + }, + "cloudtrail": { --> The CloudTrail events affecting the affected resource + "RunInstances": { --> The CloudTrail event name + "Username": "test", --> The username of the event, if any + "EventTime": "2021-01-01T00:00:00Z", + "EventId": "12345678-1234-1234-1234-123456789012", + } + }, + "impact": { --> The impact of the affected resource + "exposure": {...}, --> The exposure impact + "access": {...}, --> The access impact + "encryption": {...}, --> The encryption impact + "status": {...}, --> The status impact + "environment": {...}, --> The environment impact + "application": {...}, --> The application impact + "owner": {...}, --> The owner impact + "findings": {...}, --> The findings impact + "score": {...} --> The total impact score + } +} ``` ### JSON-Inventory Show a list of all resources with their ARN. -``` +```json [ "arn:aws:sagemaker:us-east-1:ofuscated:notebook-instance/obfuscated", "arn:aws:sagemaker:eu-west-1:ofuscated:notebook-instance/obfuscated" @@ -622,12 +1216,12 @@ Show a list of all resources with their ARN. Show statistics for each field/value. In the output, you will see each field/value and the number of occurrences; for example, the following output shows statistics for six findings. -``` +```json { "Title": { "SageMaker.1 Amazon SageMaker notebook instances should not have direct internet access": 2, "SageMaker.2 SageMaker notebook instances should be launched in a custom VPC": 2, - "SageMaker.3 Users should not have root access to SageMaker notebook instances": 2, + "SageMaker.3 Users should not have root access to SageMaker notebook instances": 2 }, "SeverityLabel": { "HIGH": 6 @@ -844,7 +1438,9 @@ Examples: ./metahub --sh-filters RecordState=ACTIVE WorkflowStatus=NEW ResourceType=AwsEc2SecurityGroup --mh-filters-tags Environment=Production ``` -# Updating Workflow Status +# Security Hub Actions + +## Updating Workflow Status You can use **MetaHub** to update your AWS Security Hub Findings workflow status (`NOTIFIED,` `NEW,` `RESOLVED,` `SUPPRESSED`) with a single command. You will use the `--update-findings` option to update all the findings from your MetaHub query. This means you can update one, ten, or thousands of findings using only one command. AWS Security Hub API is limited to 100 findings per update. Metahub will split your results into 100 items chucks to avoid this limitation and update your findings beside the amount. @@ -866,7 +1462,7 @@ Running the following update command will update those six findings' workflow st The `--update-findings` will ask you for confirmation before updating your findings. You can skip this confirmation by using the option `--no-actions-confirmation`. -# Enriching Findings +## Enriching Findings You can use **MetaHub** to enrich back your AWS Security Hub Findings with Context outputs using the option `--enrich-findings`. Enriching your findings means updating them directly in AWS Security Hub. **MetaHub** uses the `UserDefinedFields` field for this. @@ -884,124 +1480,6 @@ For example, you want to enrich all AWS Security Hub findings with `WorkflowStat The `--enrich-findings` will ask you for confirmation before enriching your findings. You can skip this confirmation by using the option `--no-actions-confirmation`. -# Findings Aggregation - -Working with Security Findings sometimes introduces the problem of Shadowing and Duplication. - -Shadowing is when two checks refer to the same issue, but one in a more generic way than the other one. - -Duplication is when you use more than one scanner and get the same problem from more than one. - -Think of a Security Group with port 3389/TCP open to 0.0.0.0/0. Let's use Security Hub findings as an example. - -If you are using one of the default Security Standards like `AWS-Foundational-Security-Best-Practices,` you will get two findings for the same issue: - -- `EC2.18 Security groups should only allow unrestricted incoming traffic for authorized ports` -- `EC2.19 Security groups should not allow unrestricted access to ports with high risk` - -If you are also using the standard CIS AWS Foundations Benchmark, you will also get an extra finding: - -- `4.2 Ensure no security groups allow ingress from 0.0.0.0/0 to port 3389` - -Now, imagine that SG is not in use. In that case, Security Hub will show an additional fourth finding for your resource! - -- `EC2.22 Unused EC2 security groups should be removed` - -So now you have in your dashboard four findings for one resource! - -Suppose you are working with multi-account setups and many resources. In that case, this could result in many findings that refer to the same thing without adding any extra value to your analysis. - -**MetaHub** aggregates security findings under the affected resource. - -This is how MetaHub shows the previous example with output-mode json-short: - -```sh -"arn:aws:ec2:eu-west-1:01234567890:security-group/sg-01234567890": { - "findings": [ - "EC2.19 Security groups should not allow unrestricted access to ports with high risk", - "EC2.18 Security groups should only allow unrestricted incoming traffic for authorized ports", - "4.2 Ensure no security groups allow ingress from 0.0.0.0/0 to port 3389", - "EC2.22 Unused EC2 security groups should be removed" - ], - "AwsAccountId": "01234567890", - "Region": "eu-west-1", - "ResourceType": "AwsEc2SecurityGroup" -} -``` - -This is how MetaHub shows the previous example with output-mode json-full: - -```sh -"arn:aws:ec2:eu-west-1:01234567890:security-group/sg-01234567890": { - "findings": [ - { - "EC2.19 Security groups should not allow unrestricted access to ports with high risk": { - "SeverityLabel": "CRITICAL", - "Workflow": { - "Status": "NEW" - }, - "RecordState": "ACTIVE", - "Compliance": { - "Status": "FAILED" - }, - "Id": "arn:aws:security hub:eu-west-1:01234567890:subscription/aws-foundational-security-best-practices/v/1.0.0/EC2.22/finding/01234567890-1234-1234-1234-01234567890", - "ProductArn": "arn:aws:security hub:eu-west-1::product/aws/security hub" - } - }, - { - "EC2.18 Security groups should only allow unrestricted incoming traffic for authorized ports": { - "SeverityLabel": "HIGH", - "Workflow": { - "Status": "NEW" - }, - "RecordState": "ACTIVE", - "Compliance": { - "Status": "FAILED" - }, - "Id": "arn:aws:security hub:eu-west-1:01234567890:subscription/aws-foundational-security-best-practices/v/1.0.0/EC2.22/finding/01234567890-1234-1234-1234-01234567890", - "ProductArn": "arn:aws:security hub:eu-west-1::product/aws/security hub" - } - }, - { - "4.2 Ensure no security groups allow ingress from 0.0.0.0/0 to port 3389": { - "SeverityLabel": "HIGH", - "Workflow": { - "Status": "NEW" - }, - "RecordState": "ACTIVE", - "Compliance": { - "Status": "FAILED" - }, - "Id": "arn:aws:security hub:eu-west-1:01234567890:subscription/aws-foundational-security-best-practices/v/1.0.0/EC2.22/finding/01234567890-1234-1234-1234-01234567890", - "ProductArn": "arn:aws:security hub:eu-west-1::product/aws/security hub" - } - }, - { - "EC2.22 Unused EC2 security groups should be removed": { - "SeverityLabel": "MEDIUM", - "Workflow": { - "Status": "NEW" - }, - "RecordState": "ACTIVE", - "Compliance": { - "Status": "FAILED" - }, - "Id": "arn:aws:security hub:eu-west-1:01234567890:subscription/aws-foundational-security-best-practices/v/1.0.0/EC2.22/finding/01234567890-1234-1234-1234-01234567890", - "ProductArn": "arn:aws:security hub:eu-west-1::product/aws/security hub" - } - } - ], - "AwsAccountId": "01234567890", - "AwsAccountAlias": "obfuscated", - "Region": "eu-west-1", - "ResourceType": "AwsEc2SecurityGroup" -} -``` - -Your findings are combined under the ARN of the resource affected, ending in only one result or one non-compliant resource. - -You can now work in MetaHub with all these four findings together as if they were only one. For example, you can update these four Workflow Status findings using only one command: See [Updating Workflow Status](#updating-workflow-status) - # Contributing You can follow this guide if you want to contribute to the Context module [guide](docs/context.md). diff --git a/docs/context.md b/docs/context.md index e0f3fc3..8478c7b 100644 --- a/docs/context.md +++ b/docs/context.md @@ -1,71 +1,108 @@ -# Context Development +# Context Module -The ResourceType defines the MetaChecks to be executed. When there is an AWS Security Hub finding for an S3 Bucket (ResourceType: AwsS3Bucket), all the MetaChecks available for that resource will execute and be added as extra information under the ARNs resource. +The context module has 4 main components: config, tags, account and cloudtrail. -- [How it works](#how-it-works) -- [Adding a new AWS ResourceType for MetaChecks](#adding-a-new-aws-resourcetype-for-metachecks) -- [Creating MetaChecks](#creating-metachecks) +The config component is responsible for fetching the configuration and the associated resources. This configuration and associated resources are defined by resource type, under `lib/context/resources` you will find a file for each resource type. -## How it works +## Adding a new AWS ResourceType -Context works this way: +If you want to add context for a ResourceType that has not yet been defined in MetaHub, you will first need to add the ResourceType as a Class: -1. Connect to the account where the resource lives assuming the provided role (`--mh-assume-role`) -2. Describe the resource using describe functions -3. Executes MetaChecks on top of the described resource -4. Add the MetaChecks output to your affected resources -5. Apply filters if provided (`--mh-filters-checks`) -6. Output the list of affected resources with MetaChecks outputs that matchs your filters +1. Create a new file under `lib/context/resources` with the ResourceType as name, for example `AwsS3Bucket.py` -## Adding a new AWS ResourceType for MetaChecks +2. Start with this template as a base. We are using a base Class MetaChecksBase for every ResourceType. -If you want to add MetaChecks for a ResourceType that has not yet been defined in MetaHub, you will first need to add the ResourceType as a Class: +```python +"""ResourceType: Name of the ResourceType""" -1. Create a new file under `metachecks/checks` with the ResourceType as name, for example `AwsS3Bucket.py` - -2. Start with this template as a base. We are using a base Class (MetaChecksBase) to provide the filtering functionality. - -``` -'''MetaCheck: ''' +from botocore.exceptions import ClientError from lib.AwsHelpers import get_boto3_client -from lib.metachecks.checks.Base import MetaChecksBase -from lib.context.resources.MetaChecksHelpers import IamHelper +from lib.context.resources.Base import ContextBase -class Metacheck(MetaChecksBase): +class Metacheck(ContextBase): def __init__( self, logger, finding, - metachecks, - mh_filters_checks, + mh_filters_config, sess, drilled=False, ): self.logger = logger - if metachecks: - self.region = finding["Region"] - self.account = finding["AwsAccountId"] - self.partition = finding["Resources"][0]["Id"].split(":")[1] - self.finding = finding - self.sess = sess - self.resource_arn = finding["Resources"][0]["Id"] - self.resource_id = finding["Resources"][0]["Id"].split("/")[1] - self.mh_filters_checks = mh_filters_checks - self.client = get_boto3_client(self.logger, "ec2", self.region, self.sess) + self.sess = sess + self.mh_filters_config = mh_filters_config + self.parse_finding(finding, drilled) + self.client = get_boto3_client(self.logger, "SERVICE", self.region, self.sess) --> YOUR BOTO3 CLIENT + # Describe Resource + self.RESOURCE_TYPE = self.describe_RESOURCE_TYPE() --> You will need a describe function for your resource type + if not self.RESOURCE_TYPE: --> Handling if the resource does not exist + return False + # Drilled Associations + self.iam_roles = self._describe_instance_iam_roles() --> Add your associations, needs to be a dictionary {"arn": {}} + + # Parse --> How to parse the resource id from the ARN + def parse_finding(self, finding, drilled): + self.finding = finding + self.region = finding["Region"] + self.account = finding["AwsAccountId"] + self.partition = finding["Resources"][0]["Id"].split(":")[1] + self.resource_type = finding["Resources"][0]["Type"] + self.resource_id = ( --> When the resource is drilled, it get's the arn as drilled + finding["Resources"][0]["Id"].split("/")[-1] + if not drilled + else drilled.split("/")[-1] + ) + self.resource_arn = finding["Resources"][0]["Id"] if not drilled else drilled --> When the resource is drilled, it get's the arn as drilled + + # Describe Functions + + def describe_RESOURCE_TYPE(self): --> Describe function for your resource type + try: + response = self.client.describe_instances( + InstanceIds=[ + self.resource_id, + ], + Filters=[ + { + "Name": "instance-state-name", + "Values": [ + "pending", + "running", + "shutting-down", + "stopping", + "stopped", + ], + } + ], ) + if response["Reservations"]: + return response["Reservations"][0]["Instances"][0] + except ClientError as err: + if not err.response["Error"]["Code"] == "InvalidInstanceID.NotFound": + self.logger.error( + "Failed to describe_instance: {}, {}".format(self.resource_id, err) + ) + return False + + # Context Config + + + def associations(self): + associations = {} --> The associations + return associations def checks(self): - checks = [ - ] + checks = {} --> The config checks return checks + ``` -3. Define _describe functions_ for the ResourceType. These functions will fetch the information you need to then create checks on top of it. For example, if you want to check if an S3 bucket has a public ACL, you first describe the ACLS and then create a function to check if those ACLS are public. This way, you can re-use the describe output for any necessary check. Describe functions in MetaHub are named starting with a `_` as a naming convention. These describe functions will be then be class attributes. +3. Define as many describe functions for the ResourceType you need. These functions will fetch the information you need to then create config checks on top of it. -``` -def _get_bucket_acl(self): +```python +def get_bucket_acl(self): try: response = self.client.get_bucket_acl(Bucket=self.resource_id) except ClientError as err: @@ -74,96 +111,30 @@ def _get_bucket_acl(self): return response["Grants"] ``` -4. Define an attribute for your describe function, in the previous example, we created a function to describe the ACLs (`_get_bucket_acl`) so we will call this attribute `bucket_acl` - -``` -'''MetaCheck: ''' - -from lib.AwsHelpers import get_boto3_client -from lib.metachecks.checks.Base import MetaChecksBase -from lib.context.resources.MetaChecksHelpers import IamHelper +4. Define config check functions to add keys to the config key, and add those functions to the checks function. +```python +def public_dns(self): + public_dns = False + if self.instance: + public_dns = self.instance.get("PublicDnsName") + return public_dns -class Metacheck(MetaChecksBase): - def __init__( - self, - logger, - finding, - metachecks, - mh_filters_checks, - sess, - drilled=False, - ): - self.logger = logger - if metachecks: - self.region = finding["Region"] - self.account = finding["AwsAccountId"] - self.partition = finding["Resources"][0]["Id"].split(":")[1] - self.finding = finding - self.sess = sess - self.resource_arn = finding["Resources"][0]["Id"] - self.resource_id = finding["Resources"][0]["Id"].split("/")[1] - self.mh_filters_checks = mh_filters_checks - self.client = get_boto3_client(self.logger, "ec2", self.region, self.sess) - ) - # Describe functions - self.bucket_acl = self._get_bucket_acl() --> YOUR DESCRIBE FUNCTION AS AN ATTRIBUTE - - def checks(self): - checks = [ - ] - return checks +def checks(self): + checks = { + "public_dns": self.public_dns(), + } + return checks ``` -5. Import Metacheck in metachecks/checks/**init**.py file - -## Creating MetaChecks - -You can code any check you need on top of the data fetched by the _describe functions_. - -A MetaCheck should be defined as a yes/no question; when the answer is yes, we can add extra information. When it is no, we can return False or empty data ("", [], {}). For example, if we check if an S3 ACL is public, we can return the permissions that make that ACL public, like READ or FULL_CONTROL. -When filtering using Meta Checks, we evaluate True as True and True if we return data. So you can output extra information for your resources this way and then integrate it with other tools. As another example, if you are checking a Security Group for unrestrictive open ports, you can output which ports are open and then use that to integrate with Nmap for scanning. +5. Add the associated resources to the associations function. +```python +def associations(self): + associations = { + "iam_roles": self.iam_roles, + } + return associations ``` -def is_bucket_acl_public(self): - public_acls = [] - if self.bucket_acl: - for grant in self.bucket_acl: - if grant["Grantee"]["Type"] == "Group": - who = grant["Grantee"]["URI"].split("/")[-1] - if who == "AllUsers" or who == "AuthenticatedUsers": - perm = grant["Permission"] - public_acls.append(perm) - if public_acls: - return public_acls - return False -``` - -This function will return the permissions allowed to public (like FULL_CONTROL or READ) or will return False if it's not public. -``` -def it_has_bucket_acl_with_cross_account(self): - acl_with_cross_account = [] - if self.bucket_acl: - for grant in self.bucket_acl: - if grant["Grantee"]["Type"] == "CanonicalUser": - if grant["Grantee"]["ID"] != self.cannonical_user_id: - perm = grant["Permission"] - acl_with_cross_account.append(perm) - if acl_with_cross_account: - return acl_with_cross_account - return False -``` - -This function will return the permissions that were granted to other accounts (like FULL_CONTROL or READ) or will return False if it was not granted to other accounts. - -To enable the check, add it to the list in the fuction `checks` of your `ResourceType`. - -``` - def checks(self): - checks = [ - "it_has_bucket_acl_with_cross_account", - "is_bucket_acl_public" - ] - return checks -``` +4. Import Metacheck in lib/resources/**init**.py file diff --git a/docs/imgs/impact.png b/docs/imgs/impact.png new file mode 100644 index 0000000000000000000000000000000000000000..7bfa62be69e5974a24712cc45f7ce199a0683e04 GIT binary patch literal 67019 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

ZPRG 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 G0skM68w+Uw literal 0 HcmV?d00001 diff --git a/lib/actions.py b/lib/actions.py new file mode 100644 index 0000000..104bbe5 --- /dev/null +++ b/lib/actions.py @@ -0,0 +1,97 @@ +from lib.findings import count_mh_findings +from lib.helpers import confirm_choice, print_table, print_title_line + + +class Actions: + def __init__(self, logger, args, mh_findings, sh): + self.logger = logger + self.args = args + self.mh_findings = mh_findings + self.sh = sh + + def update_findings(self, update_filters): + UPProcessedFindings = [] + UPUnprocessedFindings = [] + print_title_line("Update Findings", banners=self.args.banners) + print_table( + "Findings to update: ", + str(count_mh_findings(self.mh_findings)), + banners=self.args.banners, + ) + print_table( + "Update: ", str(self.args.update_findings), banners=self.args.banners + ) + + # Lambda output + if "lambda" in self.args.output_modes: + print( + "Updating findings: ", + str(count_mh_findings(self.mh_findings)), + "with:", + str(self.args.update_findings), + ) + + if self.mh_findings and confirm_choice( + "Are you sure you want to update all findings?", + self.args.actions_confirmation, + ): + update_multiple = self.sh.update_findings_workflow( + self.mh_findings, update_filters + ) + for update in update_multiple: + for ProcessedFinding in update["ProcessedFindings"]: + self.logger.info("Updated Finding : " + ProcessedFinding["Id"]) + UPProcessedFindings.append(ProcessedFinding) + for UnprocessedFinding in update["UnprocessedFindings"]: + self.logger.error( + "Error Updating Finding: " + + UnprocessedFinding["FindingIdentifier"]["Id"] + + " Error: " + + UnprocessedFinding["ErrorMessage"] + ) + UPUnprocessedFindings.append(UnprocessedFinding) + + self.print_processed(UPProcessedFindings, UPUnprocessedFindings) + + def enrich_findings(self): + ENProcessedFindings = [] + ENUnprocessedFindings = [] + print_title_line("Enrich Findings", banners=self.args.banners) + print_table( + "Findings to enrich: ", + str(count_mh_findings(self.mh_findings)), + banners=self.args.banners, + ) + + # Lambda output + if "lambda" in self.args.output_modes: + print("Enriching findings: ", str(count_mh_findings(self.mh_findings))) + + if self.mh_findings and confirm_choice( + "Are you sure you want to enrich all findings?", + self.args.actions_confirmation, + ): + update_multiple = self.sh.update_findings_meta(self.mh_findings) + for update in update_multiple: + for ProcessedFinding in update["ProcessedFindings"]: + self.logger.info("Updated Finding : " + ProcessedFinding["Id"]) + ENProcessedFindings.append(ProcessedFinding) + for UnprocessedFinding in update["UnprocessedFindings"]: + self.logger.error( + "Error Updating Finding: " + + UnprocessedFinding["FindingIdentifier"]["Id"] + + " Error: " + + UnprocessedFinding["ErrorMessage"] + ) + ENUnprocessedFindings.append(UnprocessedFinding) + + self.print_processed(ENProcessedFindings, ENUnprocessedFindings) + + def print_processed(self, processed, unprocessed): + print_title_line("Results", banners=self.args.banners) + print_table( + "ProcessedFindings: ", str(len(processed)), banners=self.args.banners + ) + print_table( + "UnprocessedFindings: ", str(len(unprocessed)), banners=self.args.banners + ) diff --git a/lib/config/impact.yaml b/lib/config/impact.yaml index 09ca298..c515969 100644 --- a/lib/config/impact.yaml +++ b/lib/config/impact.yaml @@ -4,7 +4,7 @@ # Weight: Maximum score for this property # Values: List of values for this property # - Name: Name of the value -# Score: Score for this value +# Score: Score for this value, between 0 and 1. If no match, the property impact property is not scored. status: weight: 50 @@ -21,6 +21,8 @@ status: score: 1 - not-enabled: score: 0 + # If you want to count unknown as a score of 0, enabling the impact property when no match. + # Uncomment the following lines # - unknown: # score: 0 @@ -37,6 +39,8 @@ exposure: score: 0.1 - restricted: score: 0 + # If you want to count unknown as a score of 0, enabling the impact property when no match. + # Uncomment the following lines # - unknown: # score: 0 @@ -59,7 +63,8 @@ access: score: 0.1 - restricted: score: 0 - # - unknown: + # If you want to count unknown as a score of 0, enabling the impact property when no match. + # Uncomment the following lines # score: 0 encryption: @@ -69,7 +74,8 @@ encryption: score: 1 - encrypted: score: 0 - # - unknown: + # If you want to count unknown as a score of 0, enabling the impact property when no match. + # Uncomment the following lines # score: 0 environment: @@ -81,7 +87,8 @@ environment: score: 0.3 - development: score: 0 - # - unknown: + # If you want to count unknown as a score of 0, enabling the impact property when no match. + # Uncomment the following lines # score: 0 application: @@ -91,7 +98,8 @@ application: score: 1 - app2: score: 0.5 - # - unknown: + # If you want to count unknown as a score of 0, enabling the impact property when no match. + # Uncomment the following lines # score: 0 owner: @@ -101,5 +109,6 @@ owner: score: 1 - owner2: score: 0.5 - # - unknown: + # If you want to count unknown as a score of 0, enabling the impact property when no match. + # Uncomment the following lines # score: 0 diff --git a/lib/findings.py b/lib/findings.py index cfe9b51..9e9959c 100644 --- a/lib/findings.py +++ b/lib/findings.py @@ -4,78 +4,12 @@ from alive_progress import alive_bar from lib.context.context import Context -from lib.helpers import confirm_choice, print_table +from lib.helpers import print_table from lib.impact.impact import Impact from lib.securityhub import SecurityHub, parse_finding from lib.statistics import generate_statistics -def update_findings( - logger, - mh_findings, - update, - sh_account, - sh_role, - sh_region, - update_filters, - sh_profile, - actions_confirmation, -): - sh = SecurityHub(logger, sh_region, sh_account, sh_role, sh_profile) - if confirm_choice( - "Are you sure you want to update all findings?", actions_confirmation - ): - update_multiple = sh.update_findings_workflow(mh_findings, update_filters) - update_multiple_ProcessedFinding = [] - update_multiple_UnprocessedFindings = [] - for update in update_multiple: - for ProcessedFinding in update["ProcessedFindings"]: - logger.info("Updated Finding : " + ProcessedFinding["Id"]) - update_multiple_ProcessedFinding.append(ProcessedFinding) - for UnprocessedFinding in update["UnprocessedFindings"]: - logger.error( - "Error Updating Finding: " - + UnprocessedFinding["FindingIdentifier"]["Id"] - + " Error: " - + UnprocessedFinding["ErrorMessage"] - ) - update_multiple_UnprocessedFindings.append(UnprocessedFinding) - return update_multiple_ProcessedFinding, update_multiple_UnprocessedFindings - return [], [] - - -def enrich_findings( - logger, - mh_findings, - sh_account, - sh_role, - sh_region, - sh_profile, - actions_confirmation, -): - sh = SecurityHub(logger, sh_region, sh_account, sh_role, sh_profile) - if confirm_choice( - "Are you sure you want to enrich all findings?", actions_confirmation - ): - update_multiple = sh.update_findings_meta(mh_findings) - update_multiple_ProcessedFinding = [] - update_multiple_UnprocessedFindings = [] - for update in update_multiple: - for ProcessedFinding in update["ProcessedFindings"]: - logger.info("Updated Finding : " + ProcessedFinding["Id"]) - update_multiple_ProcessedFinding.append(ProcessedFinding) - for UnprocessedFinding in update["UnprocessedFindings"]: - logger.error( - "Error Updating Finding: " - + UnprocessedFinding["FindingIdentifier"]["Id"] - + " Error: " - + UnprocessedFinding["ErrorMessage"] - ) - update_multiple_UnprocessedFindings.append(UnprocessedFinding) - return update_multiple_ProcessedFinding, update_multiple_UnprocessedFindings - return [], [] - - def generate_findings( logger, sh_filters, @@ -188,16 +122,13 @@ def process_finding(finding): # Generate Impact imp = Impact(logger) - for resource_arn, resource_values in mh_findings.items(): - impact_checks = imp.generate_impact_checks(resource_arn, resource_values) + for resource_arn in mh_findings: + impact_checks = imp.generate_impact_checks( + resource_arn, mh_findings[resource_arn] + ) mh_findings[resource_arn]["impact"] = mh_findings_short[resource_arn][ "impact" ] = impact_checks - for resource_arn, resource_values in mh_findings.items(): - impact_scoring = imp.generate_impact_scoring(resource_arn, resource_values) - mh_findings[resource_arn]["impact"]["score"] = mh_findings_short[resource_arn][ - "impact" - ]["score"] = impact_scoring # Generate Statistics mh_statistics = generate_statistics(mh_findings) @@ -361,3 +292,10 @@ def evaluate_finding( mh_inventory, AwsAccountData, ) + + +def count_mh_findings(mh_findings): + count = 0 + for resource in mh_findings: + count += len(mh_findings[resource]["findings"]) + return count diff --git a/lib/helpers.py b/lib/helpers.py index 24ca793..f1a8a99 100644 --- a/lib/helpers.py +++ b/lib/helpers.py @@ -1,10 +1,16 @@ import argparse +import json import logging import sys -from rich.panel import Panel - -from lib.AwsHelpers import get_available_regions +from lib.AwsHelpers import ( + get_account_alias, + get_account_id, + get_available_regions, + get_region, +) +from lib.config.configuration import sh_default_filters +from lib.securityhub import set_sh_filters class KeyValueWithList(argparse.Action): @@ -385,68 +391,147 @@ def test_python_version(): return True -def rich_box(resource_type, values): - title = resource_type - value = values - # return f"[b]{title}[/b]\n[yellow]{value}" - return f"[b]{title.center(20)}[/b]\n[bold][yellow]{str(value).center(20)}" - - -def rich_box_severity(severity, values): - color = { - "CRITICAL": "red", - "HIGH": "red", - "MEDIUM": "yellow", - "LOW": "green", - "INFORMATIONAL": "white", - } - title = "[" + color[severity] + "] " + severity + "[/]" - value = values - return f"[b]{title.center(5)}[/b]\n[bold]{str(value).center(5)}" - - -def generate_rich(mh_statistics): - severity_renderables = [] - for severity in ("CRITICAL", "HIGH", "MEDIUM", "LOW", "INFORMATIONAL"): - severity_renderables.append( - Panel( - rich_box_severity( - severity, mh_statistics["SeverityLabel"].get(severity, 0) - ), - expand=False, - padding=(1, 10), +def validate_arguments(args, logger): + # Validate no filters when using file-asff only + if "file-asff" in args.inputs and "securityhub" not in args.inputs: + if args.sh_template or args.sh_filters: + logger.error( + "--sh-filters not supported for file-asff... If you want to fetch from securityhub and file-asff at the same time use --inputs file-asff securityhub" + ) + exit(1) + + # Validate file-asff + if "file-asff" in args.inputs: + if not args.input_asff: + logger.error( + "file-asff input specified but not --input-asff, specify the input file with --input-asff" + ) + exit(1) + asff_findings = [] + for file in args.input_asff: + try: + with open(file) as f: + asff_findings.extend(json.load(f)) + except (json.decoder.JSONDecodeError, FileNotFoundError) as err: + logger.error("--input-asff file %s %s!", args.input_asff, str(err)) + exit(1) + elif args.input_asff and "file-asff" not in args.inputs: + logger.error( + "--input-asff specified but not file-asff input. Use --inputs file-asff to use --input-asff" + ) + exit(1) + else: + asff_findings = False + + # Validate Security Hub Filters + if not args.sh_filters and not args.sh_template: + sh_filters = set_sh_filters(sh_default_filters) + elif args.sh_template: + from pathlib import Path + + import yaml + + try: + yaml_to_dict = yaml.safe_load(Path(args.sh_template).read_text()) + dict_values = next(iter(yaml_to_dict.values())) + sh_filters = dict_values + except (yaml.scanner.ScannerError, FileNotFoundError) as err: + logger.error("SH Template %s reading error: %s", args.sh_template, str(err)) + exit(1) + else: + sh_filters = args.sh_filters + sh_filters = set_sh_filters(sh_filters) + + # Validate Config filters + mh_filters_config = args.mh_filters_config or {} + for mh_filter_config_key, mh_filter_config_value in mh_filters_config.items(): + if mh_filters_config[mh_filter_config_key].lower() == "true": + mh_filters_config[mh_filter_config_key] = bool(True) + elif mh_filters_config[mh_filter_config_key].lower() == "false": + mh_filters_config[mh_filter_config_key] = bool(False) + else: + logger.error( + "Only True or False it is supported for Context Config filters: " + + str(mh_filters_config) ) + exit(1) + + # Validate Tags filters + mh_filters_tags = args.mh_filters_tags or {} + + # Parameter Validation: --sh-account and --sh-assume-role + if bool(args.sh_account) != bool(args.sh_assume_role): + logger.error( + "Parameter error: --sh-assume-role and sh-account must be provided together, but only 1 provided." + ) + exit(1) + + # AWS Security Hub + if "securityhub" in args.inputs: + sh_region = args.sh_region or get_region(logger) + sh_account = args.sh_account or get_account_id( + logger, sess=None, profile=args.sh_profile + ) + sh_account_alias = get_account_alias( + logger, sh_account, role_name=args.sh_assume_role, profile=args.sh_profile + ) + else: + sh_region = args.sh_region + sh_account = args.sh_account + sh_account_alias = "" + sh_account_alias_str = ( + " (" + str(sh_account_alias) + ")" if str(sh_account_alias) else "" + ) + + # Validate Security Hub input + if "securityhub" in args.inputs and (not sh_region or not sh_account): + logger.error( + "Security Hub is defined as input for findings, but no region or account was found. Check your credentials and/or use --sh-region and --sh-account." ) - resource_type_renderables = [ - Panel(rich_box(resource_type, values), expand=True) - for resource_type, values in mh_statistics["ResourceType"].items() - ] - workflows_renderables = [ - Panel(rich_box(workflow, values), expand=True) - for workflow, values in mh_statistics["Workflow"].items() - ] - region_renderables = [ - Panel(rich_box(Region, values), expand=True) - for Region, values in mh_statistics["Region"].items() - ] - accountid_renderables = [ - Panel(rich_box(AwsAccountId, values), expand=True) - for AwsAccountId, values in mh_statistics["AwsAccountId"].items() - ] - recordstate_renderables = [ - Panel(rich_box(RecordState, values), expand=True) - for RecordState, values in mh_statistics["RecordState"].items() - ] - compliance_renderables = [ - Panel(rich_box(Compliance, values), expand=True) - for Compliance, values in mh_statistics["Compliance"].items() - ] + exit(1) + + # Validate udpate findings + update_findings_filters = {} + if args.update_findings: + IsNnoteProvided = False + IsAllowedKeyProvided = False + for key, value in args.update_findings.items(): + if key in ("Workflow", "Note"): + if key == "Workflow": + WorkflowValues = ("NEW", "NOTIFIED", "RESOLVED", "SUPPRESSED") + if value not in WorkflowValues: + logger.error( + "Incorrect update findings workflow value. Use: " + + str(WorkflowValues) + ) + exit(1) + Workflow = {"Workflow": {"Status": value}} + update_findings_filters.update(Workflow) + IsAllowedKeyProvided = True + if key == "Note": + Note = {"Note": {"Text": value, "UpdatedBy": "MetaHub"}} + update_findings_filters.update(Note) + IsNnoteProvided = True + continue + logger.error( + "Unsuported update findings key: " + + str(key) + + " - Supported keys: Workflow and Note. Use --update-findings Workflow=NEW Note='This is an example Note'" + ) + exit(1) + if not IsAllowedKeyProvided or not IsNnoteProvided: + logger.error( + 'Update findings missing key. Use --update-findings Workflow=NEW Note="This is an example Note"' + ) + exit(1) + return ( - severity_renderables, - resource_type_renderables, - workflows_renderables, - region_renderables, - accountid_renderables, - recordstate_renderables, - compliance_renderables, + asff_findings, + sh_filters, + mh_filters_config, + mh_filters_tags, + sh_account, + sh_account_alias_str, + sh_region, + update_findings_filters, ) diff --git a/lib/impact/impact.py b/lib/impact/impact.py index faf3a14..6e33ac2 100644 --- a/lib/impact/impact.py +++ b/lib/impact/impact.py @@ -56,18 +56,17 @@ def validate_config(self, config): return True def check_property_values_with_resource( - self, property_name, property_values, resource_values + self, property_name, property_values, impact_dict ): # Check property with resource and return the matching value and score - impact = resource_values.get("impact", {}) - if property_name in impact: + if property_name in impact_dict: for value in property_values: for value_key, value_data in value.items(): - if value_key in impact[property_name]: + if value_key in impact_dict[property_name]: return value_key, value_data["score"] return False - def calculate_properties_score(self, resource_values): + def calculate_properties_score(self, impact_dict): self.logger.info("Calculating impact properties score for resource") # Initialize variables to track the meta score details and context @@ -84,7 +83,7 @@ def calculate_properties_score(self, resource_values): property_weight = self.impact_config[property]["weight"] # Check the property against the finding checked_property = self.check_property_values_with_resource( - property_name, property_values, resource_values + property_name, property_values, impact_dict ) # If the property check is not False (i.e., it has a value), # record the weight, value, and calculated score for this property @@ -119,19 +118,15 @@ def calculate_properties_score(self, resource_values): return meta_score - def generate_impact_scoring(self, resource_arn, resource_values): + def generate_impact_scoring(self, resource_arn, impact_dict): self.logger.info("Calculating impact score for resource") if not self.impact_config: return False - # Calculate the findings score using the calculate_findings_score method - findings_score = Findings(self.logger).get_findings_score( - resource_arn, resource_values - ) - findings_score = [str(key) for key in findings_score.keys()] - findings_score = float(findings_score[0]) + # Get the findings score from the impact dictionary + findings_score = float([str(key) for key in impact_dict["findings"].keys()][0]) # Calculate the impact properties score - meta_score = self.calculate_properties_score(resource_values) + meta_score = self.calculate_properties_score(impact_dict) # Check if the meta score is not "n/a" (i.e., there's context) if meta_score != "n/a" and meta_score != 0: @@ -192,4 +187,7 @@ def generate_impact_checks(self, resource_arn, resource_values): impact_dict["findings"].update( Findings(self.logger).get_findings_score(resource_arn, resource_values) ) + impact_dict["score"].update( + self.generate_impact_scoring(resource_arn, impact_dict) + ) return impact_dict diff --git a/lib/main.py b/lib/main.py index e8c4eb4..bf675dd 100755 --- a/lib/main.py +++ b/lib/main.py @@ -1,188 +1,18 @@ -import json from sys import argv, exit -from rich.columns import Columns -from rich.console import Console - -from lib.AwsHelpers import get_account_alias, get_account_id, get_region -from lib.config.configuration import sh_default_filters -from lib.findings import enrich_findings, generate_findings, update_findings +from lib.actions import Actions +from lib.findings import generate_findings from lib.helpers import ( - generate_rich, get_logger, get_parser, print_banner, - print_color, print_table, print_title_line, test_python_version, + validate_arguments, ) -from lib.outputs import generate_outputs - - -def count_mh_findings(mh_findings): - count = 0 - for resource in mh_findings: - count += len(mh_findings[resource]["findings"]) - return count - - -def set_sh_filters(sh_filters): - """Return filters for AWS Security Hub get_findings Call""" - filters = {} - for key, values in sh_filters.items(): - if key != "self" and values is not None: - filters[key] = [] - for value in values: - value_to_append = {"Comparison": "EQUALS", "Value": value} - filters[key].append(value_to_append) - return filters - - -def validate_arguments(args, logger): - # Validate no filters when using file-asff only - if "file-asff" in args.inputs and "securityhub" not in args.inputs: - if args.sh_template or args.sh_filters: - logger.error( - "--sh-filters not supported for file-asff... If you want to fetch from securityhub and file-asff at the same time use --inputs file-asff securityhub" - ) - exit(1) - - # Validate file-asff - if "file-asff" in args.inputs: - if not args.input_asff: - logger.error( - "file-asff input specified but not --input-asff, specify the input file with --input-asff" - ) - exit(1) - asff_findings = [] - for file in args.input_asff: - try: - with open(file) as f: - asff_findings.extend(json.load(f)) - except (json.decoder.JSONDecodeError, FileNotFoundError) as err: - logger.error("--input-asff file %s %s!", args.input_asff, str(err)) - exit(1) - elif args.input_asff and "file-asff" not in args.inputs: - logger.error( - "--input-asff specified but not file-asff input. Use --inputs file-asff to use --input-asff" - ) - exit(1) - else: - asff_findings = False - - # Validate Security Hub Filters - if not args.sh_filters and not args.sh_template: - sh_filters = set_sh_filters(sh_default_filters) - elif args.sh_template: - from pathlib import Path - - import yaml - - try: - yaml_to_dict = yaml.safe_load(Path(args.sh_template).read_text()) - dict_values = next(iter(yaml_to_dict.values())) - sh_filters = dict_values - except (yaml.scanner.ScannerError, FileNotFoundError) as err: - logger.error("SH Template %s reading error: %s", args.sh_template, str(err)) - exit(1) - else: - sh_filters = args.sh_filters - sh_filters = set_sh_filters(sh_filters) - - # Validate Config filters - mh_filters_config = args.mh_filters_config or {} - for mh_filter_config_key, mh_filter_config_value in mh_filters_config.items(): - if mh_filters_config[mh_filter_config_key].lower() == "true": - mh_filters_config[mh_filter_config_key] = bool(True) - elif mh_filters_config[mh_filter_config_key].lower() == "false": - mh_filters_config[mh_filter_config_key] = bool(False) - else: - logger.error( - "Only True or False it is supported for Context Config filters: " - + str(mh_filters_config) - ) - exit(1) - - # Validate Tags filters - mh_filters_tags = args.mh_filters_tags or {} - - # Parameter Validation: --sh-account and --sh-assume-role - if bool(args.sh_account) != bool(args.sh_assume_role): - logger.error( - "Parameter error: --sh-assume-role and sh-account must be provided together, but only 1 provided." - ) - exit(1) - - # AWS Security Hub - if "securityhub" in args.inputs: - sh_region = args.sh_region or get_region(logger) - sh_account = args.sh_account or get_account_id( - logger, sess=None, profile=args.sh_profile - ) - sh_account_alias = get_account_alias( - logger, sh_account, role_name=args.sh_assume_role, profile=args.sh_profile - ) - else: - sh_region = args.sh_region - sh_account = args.sh_account - sh_account_alias = "" - sh_account_alias_str = ( - " (" + str(sh_account_alias) + ")" if str(sh_account_alias) else "" - ) - - # Validate Security Hub input - if "securityhub" in args.inputs and (not sh_region or not sh_account): - logger.error( - "Security Hub is defined as input for findings, but no region or account was found. Check your credentials and/or use --sh-region and --sh-account." - ) - exit(1) - - # Validate udpate findings - update_findings_filters = {} - if args.update_findings: - IsNnoteProvided = False - IsAllowedKeyProvided = False - for key, value in args.update_findings.items(): - if key in ("Workflow", "Note"): - if key == "Workflow": - WorkflowValues = ("NEW", "NOTIFIED", "RESOLVED", "SUPPRESSED") - if value not in WorkflowValues: - logger.error( - "Incorrect update findings workflow value. Use: " - + str(WorkflowValues) - ) - exit(1) - Workflow = {"Workflow": {"Status": value}} - update_findings_filters.update(Workflow) - IsAllowedKeyProvided = True - if key == "Note": - Note = {"Note": {"Text": value, "UpdatedBy": "MetaHub"}} - update_findings_filters.update(Note) - IsNnoteProvided = True - continue - logger.error( - "Unsuported update findings key: " - + str(key) - + " - Supported keys: Workflow and Note. Use --update-findings Workflow=NEW Note='This is an example Note'" - ) - exit(1) - if not IsAllowedKeyProvided or not IsNnoteProvided: - logger.error( - 'Update findings missing key. Use --update-findings Workflow=NEW Note="This is an example Note"' - ) - exit(1) - - return ( - asff_findings, - sh_filters, - mh_filters_config, - mh_filters_tags, - sh_account, - sh_account_alias_str, - sh_region, - update_findings_filters, - ) +from lib.outputs import Outputs +from lib.securityhub import SecurityHub def main(args): @@ -205,33 +35,37 @@ def main(args): update_findings_filters, ) = validate_arguments(args, logger) + def print_options(): + print_table("Input: ", str(args.inputs), banners=banners) + print_table( + "Security Hub Account: ", + str(sh_account) + sh_account_alias_str, + banners=banners, + ) + print_table("Security Hub Region: ", sh_region, banners=banners) + print_table("Security Hub Role: ", str(args.sh_assume_role), banners=banners) + print_table("Security Hub Profile: ", args.sh_profile, banners=banners) + print_table("Security Hub filters: ", str(sh_filters), banners=banners) + print_table("Security Hub yaml: ", str(args.sh_template), banners=banners) + print_table("Input File: ", str(args.input_asff), banners=banners) + print_table("Context Role: ", str(args.mh_assume_role), banners=banners) + print_table("Context Options: ", str(args.context), banners=banners) + print_table("Config Filters: ", str(mh_filters_config), banners=banners) + print_table("Tags Filters: ", str(mh_filters_tags), banners=banners) + print_table("Update Findings: ", str(args.update_findings), banners=banners) + print_table("Enrich Findings: ", str(args.enrich_findings), banners=banners) + print_table( + "Actions Confirmation: ", str(args.actions_confirmation), banners=banners + ) + print_table("Output Modes: ", str(args.output_modes), banners=banners) + print_table("List Findings: ", str(args.list_findings), banners=banners) + print_table("Log Level: ", str(args.log_level), banners=banners) + + # Options print_title_line("Options", banners=banners) - print_table("Input: ", str(args.inputs), banners=banners) - print_table( - "Security Hub Account: ", - str(sh_account) + sh_account_alias_str, - banners=banners, - ) - print_table("Security Hub Region: ", sh_region, banners=banners) - print_table("Security Hub Role: ", str(args.sh_assume_role), banners=banners) - print_table("Security Hub Profile: ", args.sh_profile, banners=banners) - print_table("Security Hub filters: ", str(sh_filters), banners=banners) - print_table("Security Hub yaml: ", str(args.sh_template), banners=banners) - print_table("Input File: ", str(args.input_asff), banners=banners) - print_table("Context Role: ", str(args.mh_assume_role), banners=banners) - print_table("Context Options: ", str(args.context), banners=banners) - print_table("Config Filters: ", str(mh_filters_config), banners=banners) - print_table("Tags Filters: ", str(mh_filters_tags), banners=banners) - print_table("Update Findings: ", str(args.update_findings), banners=banners) - print_table("Enrich Findings: ", str(args.enrich_findings), banners=banners) - print_table( - "Actions Confirmation: ", str(args.actions_confirmation), banners=banners - ) - print_table("Output Modes: ", str(args.output_modes), banners=banners) - print_table("List Findings: ", str(args.list_findings), banners=banners) - print_table("Log Level: ", str(args.log_level), banners=banners) + print_options() - # Generate Findings + # Reading Findings print_title_line("Reading Findings", banners=banners) ( mh_findings, @@ -254,126 +88,37 @@ def main(args): banners=banners, ) - if mh_findings: - for out in args.list_findings: - print_title_line("List Findings: " + out, banners=banners) - print( - json.dumps( - { - "short": mh_findings_short, - "inventory": mh_inventory, - "statistics": mh_statistics, - "full": mh_findings, - }[out], - indent=2, - ) - ) + # Outputs + outputs = Outputs( + logger, mh_findings, mh_findings_short, mh_inventory, mh_statistics, args + ) + + # List Findings + outputs.list_findings() + # Results print_title_line("Results", banners=banners) - print_table( - "Total Findings: ", str(count_mh_findings(mh_findings)), banners=banners - ) - print_table("Total Resources: ", str(len(mh_findings)), banners=banners) + outputs.show_results() + # Statistics print_title_line("Statistics by Findings", banners=banners) - if banners: - ( - severity_renderables, - resource_type_renderables, - workflows_renderables, - region_renderables, - accountid_renderables, - recordstate_renderables, - compliance_renderables, - ) = generate_rich(mh_statistics) - console = Console() - print_color("Severities:") - # console.print(Align.center(Group(Columns(severity_renderables)))) - console.print(Columns(severity_renderables), end="") - print_color("Resource Type:") - console.print(Columns(resource_type_renderables)) - print_color("Workflow Status:") - console.print(Columns(workflows_renderables)) - print_color("Compliance Status:") - console.print(Columns(compliance_renderables)) - print_color("Record State:") - console.print(Columns(recordstate_renderables)) - print_color("Region:") - console.print(Columns(region_renderables)) - print_color("Account ID:") - console.print(Columns(accountid_renderables)) + outputs.generate_output_rich() + # Outputs Files print_title_line("Outputs", banners=banners) - generate_outputs( - args, - mh_findings_short, - mh_inventory, - mh_statistics, - mh_findings, - banners=banners, - ) + outputs.generate_outputs() if args.update_findings: - UPProcessedFindings = [] - UPUnprocessedFindings = [] - print_title_line("Update Findings", banners=banners) - print_table( - "Findings to update: ", str(count_mh_findings(mh_findings)), banners=banners - ) - print_table("Update: ", str(args.update_findings), banners=banners) - if "lambda" in args.output_modes: - print( - "Updating findings: ", - str(count_mh_findings(mh_findings)), - "with:", - str(args.update_findings), - ) - if mh_findings: - UPProcessedFindings, UPUnprocessedFindings = update_findings( - logger, - mh_findings, - args.update_findings, - sh_account, - args.sh_assume_role, - sh_region, - update_findings_filters, - args.sh_profile, - args.actions_confirmation, - ) - print_title_line("Results", banners=banners) - print_table( - "ProcessedFindings: ", str(len(UPProcessedFindings)), banners=banners - ) - print_table( - "UnprocessedFindings: ", str(len(UPUnprocessedFindings)), banners=banners + sh = SecurityHub( + logger, sh_region, sh_account, args.sh_assume_role, args.sh_profile ) + Actions(logger, args, mh_findings, sh).update_findings(update_findings_filters) if args.enrich_findings: - ENProcessedFindings = [] - ENUnprocessedFindings = [] - print_title_line("Enrich Findings", banners=banners) - print_table( - "Findings to enrich: ", str(count_mh_findings(mh_findings)), banners=banners - ) - if "lambda" in args.output_modes: - print("Enriching findings: ", str(count_mh_findings(mh_findings))) - if mh_findings: - ENProcessedFindings, ENUnprocessedFindings = enrich_findings( - logger, - mh_findings, - sh_account, - args.sh_assume_role, - sh_region, - args.sh_profile, - args.actions_confirmation, - ) - print_title_line("Results", banners=banners) - print_table( - "ProcessedFindings: ", str(len(ENProcessedFindings)), banners=banners - ) - print_table( - "UnprocessedFindings: ", str(len(ENUnprocessedFindings)), banners=banners + sh = SecurityHub( + logger, sh_region, sh_account, args.sh_assume_role, args.sh_profile ) + Actions(logger, args, mh_findings, sh).enrich_findings() if "lambda" in args.output_modes: return mh_findings_short diff --git a/lib/outputs.py b/lib/outputs.py index bdfdff2..4b94440 100644 --- a/lib/outputs.py +++ b/lib/outputs.py @@ -4,43 +4,188 @@ import jinja2 import xlsxwriter +from rich.columns import Columns +from rich.console import Console +from rich.panel import Panel -from lib.config.configuration import outputs_dir, outputs_time_str -from lib.helpers import print_table +from lib.config.configuration import ( + account_columns, + config_columns, + impact_columns, + outputs_dir, + outputs_time_str, + tag_columns, +) +from lib.findings import count_mh_findings +from lib.helpers import print_color, print_table, print_title_line TIMESTRF = strftime(outputs_time_str) -def generate_output_json( - mh_findings_short, mh_findings, mh_inventory, mh_statistics, json_mode, args -): - WRITE_FILE = f"{outputs_dir}metahub-{json_mode}-{TIMESTRF}.json" - with open(WRITE_FILE, "w", encoding="utf-8") as f: - try: - json.dump( - { - "short": mh_findings_short, - "full": mh_findings, - "inventory": mh_inventory, - "statistics": mh_statistics, - }[json_mode], - f, - indent=2, - ) - except ValueError as e: - print("Error generating JSON Output (" + json_mode + "):", e) - print_table("JSON (" + json_mode + "): ", WRITE_FILE, banners=args.banners) +class Outputs: + def __init__( + self, logger, mh_findings, mh_findings_short, mh_inventory, mh_statistics, args + ) -> None: + self.logger = logger + self.mh_findings = mh_findings + self.mh_findings_short = mh_findings_short + self.mh_inventory = mh_inventory + self.mh_statistics = mh_statistics + self.banners = args.banners + self.args = args + # Output Columns + self.config_columns = ( + args.output_config_columns + or config_columns + or list(mh_statistics["config"].keys()) + ) + self.tag_columns = ( + args.output_tag_columns or tag_columns or list(mh_statistics["tags"].keys()) + ) + self.account_columns = ( + args.output_account_columns or account_columns or mh_statistics["account"] + ) + self.impact_columns = impact_columns or mh_statistics["impact"] + + def generate_outputs(self): + if self.mh_findings: + for ouput_mode in self.args.output_modes: + if ouput_mode.startswith("json"): + json_mode = ouput_mode.split("-")[1] + self.generate_output_json( + json_mode, + ) + if ouput_mode == "csv": + self.generate_output_csv() + if ouput_mode == "xlsx": + self.generate_output_xlsx() + if ouput_mode == "html": + self.generate_output_html() + def generate_output_json(self, json_mode): + WRITE_FILE = f"{outputs_dir}metahub-{json_mode}-{TIMESTRF}.json" + with open(WRITE_FILE, "w", encoding="utf-8") as f: + try: + json.dump( + { + "short": self.mh_findings_short, + "full": self.mh_findings, + "inventory": self.mh_inventory, + "statistics": self.mh_statistics, + }[json_mode], + f, + indent=2, + ) + except ValueError as e: + print("Error generating JSON Output (" + json_mode + "):", e) + print_table("JSON (" + json_mode + "): ", WRITE_FILE, banners=self.banners) -def generate_output_csv( - output, config_columns, tag_columns, account_columns, impact_columns, args -): - WRITE_FILE = f"{outputs_dir}metahub-{TIMESTRF}.csv" - with open(WRITE_FILE, "w", encoding="utf-8", newline="") as output_file: + def generate_output_csv(self): + WRITE_FILE = f"{outputs_dir}metahub-{TIMESTRF}.csv" + with open(WRITE_FILE, "w", encoding="utf-8", newline="") as output_file: + colums = [ + "Resource ID", + "Severity", + "Impact", + "Title", + "AWS Account ID", + "Region", + "Resource Type", + "WorkflowStatus", + "RecordState", + "ComplianceStatus", + ] + colums = ( + colums + + self.config_columns + + self.tag_columns + + self.account_columns + + self.impact_columns + ) + dict_writer = csv.DictWriter(output_file, fieldnames=colums) + dict_writer.writeheader() + # Iterate over the resources + for resource, values in self.mh_findings.items(): + for finding in values["findings"]: + for f, v in finding.items(): + tag_column_values = [] + for column in self.tag_columns: + try: + tag_column_values.append(values["tags"][column]) + except (KeyError, TypeError): + tag_column_values.append("") + config_column_values = [] + for column in self.config_columns: + try: + config_column_values.append(values["config"][column]) + except (KeyError, TypeError): + config_column_values.append("") + impact_column_values = [] + for column in self.impact_columns: + try: + impact_column_values.append(values["impact"][column]) + except (KeyError, TypeError): + impact_column_values.append("") + account_column_values = [] + for column in self.account_columns: + try: + account_column_values.append(values["account"][column]) + except (KeyError, TypeError): + account_column_values.append("") + row = ( + [ + resource, + v.get("SeverityLabel", None), + values.get("impact", None).get("Impact", None) + if values.get("impact") + else None, + f, + values.get("AwsAccountId", None), + values.get("Region", None), + values.get("ResourceType", None), + v.get("Workflow", {}).get("Status", None) + if v.get("Workflow") + else None, + v.get("RecordState", None), + v.get("Compliance", {}).get("Status", None) + if v.get("Compliance") + else None, + ] + # + impact_column_values + + account_column_values + + tag_column_values + + config_column_values + ) + dict_writer.writerow(dict(zip(colums, row))) + print_table("CSV: ", WRITE_FILE, banners=self.banners) + + def generate_output_xlsx(self): + WRITE_FILE = f"{outputs_dir}metahub-{TIMESTRF}.xlsx" + # Create a workbook and add a worksheet + workbook = xlsxwriter.Workbook(WRITE_FILE) + worksheet = workbook.add_worksheet("findings") + # Columns + worksheet.set_default_row(25) + worksheet.set_column(0, 0, 145) # Resource ID. + worksheet.set_column(1, 1, 15) # Severity. + worksheet.set_column(2, 2, 15) # Impact. + worksheet.set_column(3, 3, 105) # Title. + worksheet.set_column(4, 4, 15) # Account ID. + worksheet.set_column(5, 5, 15) # Region. + worksheet.set_column(6, 6, 25) # Resource Type. + worksheet.set_column(7, 7, 25) # WorkflowStatus. + worksheet.set_column(8, 8, 25) # RecordState. + worksheet.set_column(9, 9, 25) # ComplianceStatus. + # Formats + title_format = workbook.add_format({"bold": True, "border": 1}) + raws_format = workbook.add_format({"text_wrap": True, "border": 1}) + critical_format = workbook.add_format({"bg_color": "#7d2105", "border": 1}) + high_format = workbook.add_format({"bg_color": "#ba2e0f", "border": 1}) + medium_format = workbook.add_format({"bg_color": "#cc6021", "border": 1}) + low_format = workbook.add_format({"bg_color": "#b49216", "border": 1}) colums = [ "Resource ID", "Severity", - "Impact", "Title", "AWS Account ID", "Region", @@ -49,46 +194,57 @@ def generate_output_csv( "RecordState", "ComplianceStatus", ] - colums = ( - colums + config_columns + tag_columns + account_columns + impact_columns + worksheet.write_row( + 0, + 0, + colums + + self.config_columns + + self.tag_columns + + self.account_columns + + self.impact_columns, + title_format, ) - dict_writer = csv.DictWriter(output_file, fieldnames=colums) - dict_writer.writeheader() # Iterate over the resources - for resource, values in output.items(): + current_line = 1 + for resource, values in self.mh_findings.items(): for finding in values["findings"]: for f, v in finding.items(): + worksheet.write_row(current_line, 0, [resource], raws_format) + severity = v["SeverityLabel"] + if severity == "CRITICAL": + worksheet.write(current_line, 1, severity, critical_format) + elif severity == "HIGH": + worksheet.write(current_line, 1, severity, high_format) + elif severity == "MEDIUM": + worksheet.write(current_line, 1, severity, medium_format) + else: + worksheet.write(current_line, 1, severity, low_format) tag_column_values = [] - for column in tag_columns: + for column in self.tag_columns: try: tag_column_values.append(values["tags"][column]) except (KeyError, TypeError): tag_column_values.append("") config_column_values = [] - for column in config_columns: + for column in self.config_columns: try: config_column_values.append(values["config"][column]) except (KeyError, TypeError): config_column_values.append("") impact_column_values = [] - for column in impact_columns: + for column in self.impact_columns: try: impact_column_values.append(values["impact"][column]) except (KeyError, TypeError): impact_column_values.append("") account_column_values = [] - for column in account_columns: + for column in self.account_columns: try: account_column_values.append(values["account"][column]) except (KeyError, TypeError): account_column_values.append("") row = ( [ - resource, - v.get("SeverityLabel", None), - values.get("impact", None).get("Impact", None) - if values.get("impact") - else None, f, values.get("AwsAccountId", None), values.get("Region", None), @@ -106,219 +262,163 @@ def generate_output_csv( + tag_column_values + config_column_values ) - dict_writer.writerow(dict(zip(colums, row))) - print_table("CSV: ", WRITE_FILE, banners=args.banners) + worksheet.write_row(current_line, 2, row) + current_line += 1 + workbook.close() + print_table("XLSX: ", WRITE_FILE, banners=self.banners) + def generate_output_html(self): + WRITE_FILE = f"{outputs_dir}metahub-{TIMESTRF}.html" + templateLoader = jinja2.FileSystemLoader(searchpath="./") + templateEnv = jinja2.Environment(loader=templateLoader, autoescape=True) + TEMPLATE_FILE = "lib/html/template.html" + template = templateEnv.get_template(TEMPLATE_FILE) + # Convert Config to Boolean + for resource_arn in self.mh_findings: + keys_to_convert = ["config", "associations"] + for key in keys_to_convert: + if ( + key in self.mh_findings[resource_arn] + and self.mh_findings[resource_arn][key] + ): + for config in self.mh_findings[resource_arn][key]: + if bool(self.mh_findings[resource_arn][key][config]): + self.mh_findings[resource_arn][key][config] = True + else: + self.mh_findings[resource_arn][key][config] = False -def generate_output_xlsx( - output, config_columns, tag_columns, account_columns, impact_columns, args -): - WRITE_FILE = f"{outputs_dir}metahub-{TIMESTRF}.xlsx" - # Create a workbook and add a worksheet - workbook = xlsxwriter.Workbook(WRITE_FILE) - worksheet = workbook.add_worksheet("findings") - # Columns - worksheet.set_default_row(25) - worksheet.set_column(0, 0, 145) # Resource ID. - worksheet.set_column(1, 1, 15) # Severity. - worksheet.set_column(2, 2, 15) # Impact. - worksheet.set_column(3, 3, 105) # Title. - worksheet.set_column(4, 4, 15) # Account ID. - worksheet.set_column(5, 5, 15) # Region. - worksheet.set_column(6, 6, 25) # Resource Type. - worksheet.set_column(7, 7, 25) # WorkflowStatus. - worksheet.set_column(8, 8, 25) # RecordState. - worksheet.set_column(9, 9, 25) # ComplianceStatus. - # Formats - title_format = workbook.add_format({"bold": True, "border": 1}) - raws_format = workbook.add_format({"text_wrap": True, "border": 1}) - critical_format = workbook.add_format({"bg_color": "#7d2105", "border": 1}) - high_format = workbook.add_format({"bg_color": "#ba2e0f", "border": 1}) - medium_format = workbook.add_format({"bg_color": "#cc6021", "border": 1}) - low_format = workbook.add_format({"bg_color": "#b49216", "border": 1}) - colums = [ - "Resource ID", - "Severity", - "Title", - "AWS Account ID", - "Region", - "Resource Type", - "WorkflowStatus", - "RecordState", - "ComplianceStatus", - ] - worksheet.write_row( - 0, - 0, - colums + config_columns + tag_columns + account_columns + impact_columns, - title_format, - ) - # Iterate over the resources - current_line = 1 - for resource, values in output.items(): - for finding in values["findings"]: - for f, v in finding.items(): - worksheet.write_row(current_line, 0, [resource], raws_format) - severity = v["SeverityLabel"] - if severity == "CRITICAL": - worksheet.write(current_line, 1, severity, critical_format) - elif severity == "HIGH": - worksheet.write(current_line, 1, severity, high_format) - elif severity == "MEDIUM": - worksheet.write(current_line, 1, severity, medium_format) - else: - worksheet.write(current_line, 1, severity, low_format) - tag_column_values = [] - for column in tag_columns: - try: - tag_column_values.append(values["tags"][column]) - except (KeyError, TypeError): - tag_column_values.append("") - config_column_values = [] - for column in config_columns: - try: - config_column_values.append(values["config"][column]) - except (KeyError, TypeError): - config_column_values.append("") - impact_column_values = [] - for column in impact_columns: - try: - impact_column_values.append(values["impact"][column]) - except (KeyError, TypeError): - impact_column_values.append("") - account_column_values = [] - for column in account_columns: - try: - account_column_values.append(values["account"][column]) - except (KeyError, TypeError): - account_column_values.append("") - row = ( - [ - f, - values.get("AwsAccountId", None), - values.get("Region", None), - values.get("ResourceType", None), - v.get("Workflow", {}).get("Status", None) - if v.get("Workflow") - else None, - v.get("RecordState", None), - v.get("Compliance", {}).get("Status", None) - if v.get("Compliance") - else None, - ] - # + impact_column_values - + account_column_values - + tag_column_values - + config_column_values - ) - worksheet.write_row(current_line, 2, row) - current_line += 1 - workbook.close() - print_table("XLSX: ", WRITE_FILE, banners=args.banners) + with open(WRITE_FILE, "w", encoding="utf-8") as f: + html = template.render( + data=self.mh_findings, + statistics=self.mh_statistics, + title="MetaHub", + config_columns=self.config_columns, + tag_columns=self.tag_columns, + account_columns=self.account_columns, + impact_columns=self.impact_columns, + parameters=self.args, + ) + f.write(html) + print_table("HTML: ", WRITE_FILE, banners=self.banners) -def generate_output_html( - mh_findings, - mh_statistics, - config_columns, - tag_columns, - account_columns, - impact_columns, - args, -): - WRITE_FILE = f"{outputs_dir}metahub-{TIMESTRF}.html" - templateLoader = jinja2.FileSystemLoader(searchpath="./") - templateEnv = jinja2.Environment(loader=templateLoader, autoescape=True) - TEMPLATE_FILE = "lib/html/template.html" - template = templateEnv.get_template(TEMPLATE_FILE) - # Convert Config to Boolean - for resource_arn in mh_findings: - keys_to_convert = ["config", "associations"] - for key in keys_to_convert: - if key in mh_findings[resource_arn] and mh_findings[resource_arn][key]: - for config in mh_findings[resource_arn][key]: - if bool(mh_findings[resource_arn][key][config]): - mh_findings[resource_arn][key][config] = True - else: - mh_findings[resource_arn][key][config] = False + def generate_output_rich(self): + if self.banners: + ( + severity_renderables, + resource_type_renderables, + workflows_renderables, + region_renderables, + accountid_renderables, + recordstate_renderables, + compliance_renderables, + ) = generate_rich(self.mh_statistics) + console = Console() + print_color("Severities:") + # console.print(Align.center(Group(Columns(severity_renderables)))) + console.print(Columns(severity_renderables), end="") + print_color("Resource Type:") + console.print(Columns(resource_type_renderables)) + print_color("Workflow Status:") + console.print(Columns(workflows_renderables)) + print_color("Compliance Status:") + console.print(Columns(compliance_renderables)) + print_color("Record State:") + console.print(Columns(recordstate_renderables)) + print_color("Region:") + console.print(Columns(region_renderables)) + print_color("Account ID:") + console.print(Columns(accountid_renderables)) - with open(WRITE_FILE, "w", encoding="utf-8") as f: - html = template.render( - data=mh_findings, - statistics=mh_statistics, - title="MetaHub", - config_columns=config_columns, - tag_columns=tag_columns, - account_columns=account_columns, - impact_columns=impact_columns, - parameters=args, + def show_results(self): + print_table( + "Total Findings: ", + str(count_mh_findings(self.mh_findings)), + banners=self.banners, + ) + print_table( + "Total Resources: ", str(len(self.mh_findings)), banners=self.banners ) - f.write(html) - print_table("HTML: ", WRITE_FILE, banners=args.banners) + def list_findings(self): + if self.mh_findings: + for out in self.args.list_findings: + print_title_line("List Findings: " + out, banners=self.banners) + print( + json.dumps( + { + "short": self.mh_findings_short, + "inventory": self.mh_inventory, + "statistics": self.mh_statistics, + "full": self.mh_findings, + }[out], + indent=2, + ) + ) -def generate_outputs( - args, mh_findings_short, mh_inventory, mh_statistics, mh_findings, banners -): - from lib.config.configuration import ( - account_columns, - config_columns, - impact_columns, - tag_columns, - ) +def rich_box(resource_type, values): + title = resource_type + value = values + # return f"[b]{title}[/b]\n[yellow]{value}" + return f"[b]{title.center(20)}[/b]\n[bold][yellow]{str(value).center(20)}" - # Columns for CSV and HTML - output_config_columns = ( - args.output_config_columns - or config_columns - or list(mh_statistics["config"].keys()) - ) - output_tag_columns = ( - args.output_tag_columns or tag_columns or list(mh_statistics["tags"].keys()) - ) - output_account_columns = ( - args.output_account_columns or account_columns or mh_statistics["account"] - ) - output_impact_columns = impact_columns or mh_statistics["impact"] - if mh_findings: - for ouput_mode in args.output_modes: - if ouput_mode.startswith("json"): - json_mode = ouput_mode.split("-")[1] - generate_output_json( - mh_findings_short, - mh_findings, - mh_inventory, - mh_statistics, - json_mode, - args, - ) - if ouput_mode == "html": - generate_output_html( - mh_findings, - mh_statistics, - output_config_columns, - output_tag_columns, - output_account_columns, - output_impact_columns, - args, - ) - if ouput_mode == "csv": - generate_output_csv( - mh_findings, - output_config_columns, - output_tag_columns, - output_account_columns, - output_impact_columns, - args, - ) - if ouput_mode == "xlsx": - generate_output_xlsx( - mh_findings, - output_config_columns, - output_tag_columns, - output_account_columns, - output_impact_columns, - args, - ) +def rich_box_severity(severity, values): + color = { + "CRITICAL": "red", + "HIGH": "red", + "MEDIUM": "yellow", + "LOW": "green", + "INFORMATIONAL": "white", + } + title = "[" + color[severity] + "] " + severity + "[/]" + value = values + return f"[b]{title.center(5)}[/b]\n[bold]{str(value).center(5)}" + + +def generate_rich(mh_statistics): + severity_renderables = [] + for severity in ("CRITICAL", "HIGH", "MEDIUM", "LOW", "INFORMATIONAL"): + severity_renderables.append( + Panel( + rich_box_severity( + severity, mh_statistics["SeverityLabel"].get(severity, 0) + ), + expand=False, + padding=(1, 10), + ) + ) + resource_type_renderables = [ + Panel(rich_box(resource_type, values), expand=True) + for resource_type, values in mh_statistics["ResourceType"].items() + ] + workflows_renderables = [ + Panel(rich_box(workflow, values), expand=True) + for workflow, values in mh_statistics["Workflow"].items() + ] + region_renderables = [ + Panel(rich_box(Region, values), expand=True) + for Region, values in mh_statistics["Region"].items() + ] + accountid_renderables = [ + Panel(rich_box(AwsAccountId, values), expand=True) + for AwsAccountId, values in mh_statistics["AwsAccountId"].items() + ] + recordstate_renderables = [ + Panel(rich_box(RecordState, values), expand=True) + for RecordState, values in mh_statistics["RecordState"].items() + ] + compliance_renderables = [ + Panel(rich_box(Compliance, values), expand=True) + for Compliance, values in mh_statistics["Compliance"].items() + ] + return ( + severity_renderables, + resource_type_renderables, + workflows_renderables, + region_renderables, + accountid_renderables, + recordstate_renderables, + compliance_renderables, + ) diff --git a/lib/securityhub.py b/lib/securityhub.py index 2fee821..1066de1 100644 --- a/lib/securityhub.py +++ b/lib/securityhub.py @@ -202,3 +202,15 @@ def parse_finding(finding): }, } return finding["Resources"][0]["Id"], findings + + +def set_sh_filters(sh_filters): + """Return filters for AWS Security Hub get_findings Call""" + filters = {} + for key, values in sh_filters.items(): + if key != "self" and values is not None: + filters[key] = [] + for value in values: + value_to_append = {"Comparison": "EQUALS", "Value": value} + filters[key].append(value_to_append) + return filters