Merge pull request #17 from kmcquade/refactor/show-iam-principals

Added IAM Principals tab to the report

Author: kmcquade

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## 0.0.7 (2020-05-03)
+* Added separate tab for IAM Principals
+* HTML Report improvements - using tabs now
+* Changed the naming of some objects to make the object naming more in line with the AWS IAM API Data Types. https://docs.aws.amazon.com/IAM/latest/APIReference/API_Types.html
+
 ## 0.0.6 (2020-05-01)
 * Fix `exclude-actions` in the exclusions file - it was not being respected before.
 * Add a recursive scanning option.

cloudsplaining/bin/cloudsplaining

@@ -7,7 +7,7 @@
 """
     Cloudsplaining is an AWS IAM Assessment tool that identifies violations of least privilege and generates a risk-prioritized HTML report with a triage worksheet.
 """
-__version__ = "0.0.6"
+__version__ = "0.0.7"
 import click
 from cloudsplaining import command
 

cloudsplaining/command/scan.py

@@ -118,6 +118,8 @@ def scan_account_authorization_file(input_file, exclusions_cfg, output, all_acce
             exclusions_cfg, modify_only=True
         )
 
+    principal_policy_mapping = authorization_details.principal_policy_mapping
+
     account_name = Path(input_file).stem
 
     # Lazy method to get an account ID
@@ -145,10 +147,16 @@ def scan_account_authorization_file(input_file, exclusions_cfg, output, all_acce
     raw_data_filepath = write_results_data_file(results, raw_data_file)
     print(f"Raw data file saved: {str(raw_data_filepath)}")
 
+    # Principal policy mapping
+    principal_policy_mapping_file = os.path.join(output, f"iam-principals-{account_name}.json")
+    principal_policy_mapping_filepath = write_results_data_file(principal_policy_mapping, principal_policy_mapping_file)
+    print(f"Principals data file saved: {str(principal_policy_mapping_filepath)}")
+
     print("Creating the HTML Report")
     generate_html_report(
         account_metadata,
         results,
+        principal_policy_mapping,
         output_directory,
         exclusions_cfg,
         skip_open_report=skip_open_report,

cloudsplaining/output/findings.py

@@ -5,6 +5,7 @@
 # For full license text, see the LICENSE file in the repo root
 # or https://opensource.org/licenses/BSD-3-Clause
 import logging
+from operator import itemgetter
 from policy_sentry.util.arns import get_account_from_arn, get_resource_string
 from cloudsplaining.shared.constants import READ_ONLY_DATA_LEAK_ACTIONS
 from cloudsplaining.shared.exclusions import is_name_excluded
@@ -38,6 +39,8 @@ def json(self):
         these_findings = []
         for finding in self.findings:
             these_findings.append(finding.json)
+        # sort it
+        these_findings = sorted(these_findings, key=itemgetter("PolicyName"))
         return these_findings
 
     def __len__(self):
@@ -157,7 +160,8 @@ def data_leak_actions(self):
 
     @property
     def json(self):
-        """Return the JSON representation of the Finding. This is used in the report output and the results data file."""
+        """Return the JSON representation of the Finding.
+        This is used in the report output and the results data file."""
         result = {
             "AccountID": self.account_id,
             "ManagedBy": self.managed_by,
@@ -182,3 +186,13 @@ def json(self):
             # "TaggingActions": self.policy_document.tagging_actions_without_constraints,
         }
         return result
+
+
+class FindingsPrincipalsMapping:
+    """Holds a mapping between AuthorizationDetails.principal_policy_mapping and Findings"""
+
+    def __init__(self, findings, principal_policy_mapping):
+        # TODO: Figure out the Findings vs Principals Mapping thing later.
+        print(findings)
+        print(principal_policy_mapping)
+        print("Figure this out later")

cloudsplaining/output/html_report.py

@@ -16,21 +16,21 @@
 
 
 def generate_html_report(
-    account_metadata, results, output_directory, exclusions_cfg, skip_open_report=False
+    account_metadata, results, principal_policy_mapping, output_directory, exclusions_cfg, skip_open_report=False
 ):
     """Create IAM HTML report"""
 
     account_id = account_metadata.get("account_id")
     account_name = account_metadata.get("account_name")
     html_output_file = os.path.join(output_directory, f"iam-report-{account_name}.html")
-    sorted_results = sorted(results, key=lambda i: i["PolicyName"])
+    # sorted_results = sorted(results, key=lambda i: i["PolicyName"])
 
     # Calculate ratio of policies with PrivEsc, Permissions management, or Data leak potential
     policies_with_data_leak_potential = 0
     policies_with_permissions_management = 0
     policies_with_privilege_escalation = 0
 
-    for finding in sorted_results:
+    for finding in results:
         # These are stats we care about regardless of who manages it, as they help with prioritization
         if finding["DataExfiltrationActions"]:
             policies_with_data_leak_potential += 1
@@ -106,19 +106,25 @@ def generate_html_report(
 
     # Formatted results to feed into the HTML
     iam_report_results_formatted = {
+        # Metadata
         "account_name": account_name,
         "account_id": account_id,
         "report_generated_time": datetime.datetime.now().strftime("%Y-%m-%d"),
-        "results": sorted_results,
+        # Actual results
+        "results": results,
+        # IAM Principals
+        "principal_policy_mapping": principal_policy_mapping,
         # Write-ups rendered from markdown
         "overview_write_up": overview_html,
         "triage_guidance_write_up": triage_guidance_html,
         "remediation_guidance_write_up": remediation_guidance_html,
         "validation_guidance_write_up": validation_guidance_html,
         "glossary_write_up": glossary_html,
+        # Count of policies with these findings for the stats
         "policies_with_data_leak_potential": policies_with_data_leak_potential,
         "policies_with_privilege_escalation": policies_with_privilege_escalation,
         "policies_with_permissions_management": policies_with_permissions_management,
+        # Exclusions config for appendix and user reference
         "exclusions_configuration": yaml.dump(exclusions_cfg),
     }
 
@@ -138,4 +144,4 @@ def generate_html_report(
         webbrowser.open(url, new=2)
 
     # Create the CSV triage sheet
-    create_triage_worksheet(account_name, sorted_results, output_directory)
+    create_triage_worksheet(account_name, results, output_directory)

cloudsplaining/output/templates/guidance/4-validation.md

@@ -9,15 +9,17 @@ After you've rewritten your IAM policy, we suggest two options for validating th
 </ul>
 </div>
 
-<div id="validation-using-cloudsplaining"> <h6>Using Cloudsplaining to Validate your Remediated Policies</h6></div>
+
+<div id="validation-using-cloudsplaining"> <h5>Using Cloudsplaining to Validate your Remediated Policies</h5></div>
 
 You can validate that your remediated policy passes Cloudsplaining by running the following command:
 
 ```cloudsplaining scan-policy-file --input policy.json --exclusions-file exclusions.yml```
 
 When there are no more results, it passes!
 
-<div id="validation-using-parliament"> <h6>Using Parliament to Lint your Policies</h6></div>
+
+<div id="validation-using-parliament"> <h5>Using Parliament to Lint your Policies</h5></div>
 
 parliament is an AWS IAM linting library. It reviews policies looking for problems such as:
 

cloudsplaining/output/templates/guidance/glossary.md

@@ -49,3 +49,39 @@ An IAM identity that you can create in your account that has specific permission
 We are particularly interested in roles used for **compute services** - i.e., Compute Service Roles.
 
 This definition was taken from the AWS Documentation [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-role).
+
+<div id="definition-managed-policy"><h6>Managed Policy</h6></div>
+
+There are two types of Managed Policies: AWS-managed policies and Customer-managed policies. They are described below.
+
+Criteria for selecting Managed Policies versus Inline policies can be found in the AWS documentation [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#choosing-managed-or-inline).
+
+<div id="definition-customer-managed-policy"><h6>Customer-managed policy</h6></div>
+
+AWS documentation on Customer-managed policies can be found [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies).
+
+The following diagram illustrates customer managed policies. Each policy is an entity in IAM with its own Amazon Resource Name (ARN) that includes the policy name. Notice that the same policy can be attached to multiple principal entities—for example, the same DynamoDB-books-app policy is attached to two different IAM roles.
+
+![Customer-managed policy diagram](https://docs.aws.amazon.com/IAM/latest/UserGuide/images/policies-customer-managed-policies.diagram.png)
+
+<div id="definition-aws-managed-policy"><h6>AWS-managed policy</h6></div>
+
+An AWS managed policy is a standalone policy that is created and administered by AWS. Standalone policy means that the policy has its own Amazon Resource Name (ARN) that includes the policy name. For example, arn:aws:iam::aws:policy/IAMReadOnlyAccess is an AWS managed policy.
+
+AWS documentation on AWS-managed policies can be found [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies).
+
+The following diagram (taken from the AWS documentation) illustrates AWS managed policies. The diagram shows three AWS managed policies: AdministratorAccess, PowerUserAccess, and AWSCloudTrailReadOnlyAccess. Notice that a single AWS managed policy can be attached to principal entities in different AWS accounts, and to different principal entities in a single AWS account.
+
+![AWS-managed policy diagram](https://docs.aws.amazon.com/IAM/latest/UserGuide/images/policies-aws-managed-policies.diagram.png)
+
+<div id="definition-inline-policy"><h6>Inline Policy</h6></div>
+
+An inline policy is a policy that's embedded in an IAM identity (a user, group, or role). That is, the policy is an inherent part of the identity. You can create a policy and embed it in a identity, either when you create the identity or later.
+
+AWS documentation on inline policies can be found [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#inline-policies).
+
+The following diagram illustrates inline policies. Each policy is an inherent part of the user, group, or role. Notice that two roles include the same policy (the DynamoDB-books-app policy), but they are not sharing a single policy; each role has its own copy of the policy.
+
+![Inline policy diagram](https://docs.aws.amazon.com/IAM/latest/UserGuide/images/policies-inline-policies.diagram.png)
+
+Inline policies are useful if you want to maintain a strict one-to-one relationship between a policy and the identity that it's applied to. For example, you want to be sure that the permissions in a policy are not inadvertently assigned to an identity other than the one they're intended for. When you use an inline policy, the permissions in the policy cannot be inadvertently attached to the wrong identity. In addition, when you use the AWS Management Console to delete that identity, the policies embedded in the identity are deleted as well. That's because they are part of the principal entity.

cloudsplaining/output/templates/summary/executive-summary.html

@@ -1,5 +1,5 @@
 <p style="text-align: justify">
-  This report contains the security assessment results from Cloudsplaining, which maps out the IAM risk landscape in a report, identifies where resource ARN constraints are not used, and identifies other risks in IAM policies like Privilege Escalation<a href="#definition-privilege-escalation"><small>[1]</small></a>,  Resource Exposure<a href="#definition-resource-exposure"><small>[2]</small></a>, Infrastructure Modification<a href="#definition-infrastructure-modification"><small>[3]</small></a>, and Data Exfiltration<a href="#definition-data-exfiltration"><small>[4]</small></a>.
+  This report contains the security assessment results from <a href="https://github.com/salesforce/cloudsplaining">Cloudsplaining</a>, which maps out the IAM risk landscape in a report, identifies where resource ARN constraints are not used, and identifies other risks in IAM policies like Privilege Escalation<a href="#definition-privilege-escalation"><small>[1]</small></a>,  Resource Exposure<a href="#definition-resource-exposure"><small>[2]</small></a>, Infrastructure Modification<a href="#definition-infrastructure-modification"><small>[3]</small></a>, and Data Exfiltration<a href="#definition-data-exfiltration"><small>[4]</small></a>.
   Remediating these issues, where necessary, will help to limit the blast radius in the case of compromised AWS credentials.
 <br>
 <br>

cloudsplaining/output/templates/summary/iam-principals.html

@@ -0,0 +1,30 @@
+<p>
+  The following table shows the list of IAM Users, Groups, and Roles in the account, whether they have findings or not.
+</p>
+<span class="badge badge-default"></span>
+<table class="table table-striped table-bordered table-sm">
+  <thead>
+     <tr>
+       <th>Type</th>
+       <th>Name</th>
+       <th>Policy Type</th>
+       <th>Managed By</th>
+       <th>Policy Name</th>
+       <th>Comment</th>
+     </tr>
+  </thead>
+  <tbody>
+  {% for principal in t["principal_policy_mapping"] %}
+    <tr>
+      <td>{{ principal["Type"] }}</td>
+      <td>{{ principal["Principal"] }}</td>
+      <td>{{ principal["PolicyType"] }}{% if principal["PolicyType"] == "Managed" %} <a href="#definition-managed-policy"><small>[0]</small></a>{% endif %}{% if principal["PolicyType"] == "Inline" %} <a href="#definition-inline-policy"><small>[1]</small></a>{% endif %}</td>
+      <td>{{ principal["ManagedBy"] }}{% if principal["ManagedBy"] == "AWS" %} <a href="#definition-aws-managed-policy"><small>[2]</small></a>{% endif %}{% if principal["ManagedBy"] == "Customer" %} <a href="#definition-customer-managed-policy"><small>[3]</small></a>{% endif %}</td>
+      <td>{{ principal["PolicyName"] }}</td>
+      <td>{{ principal["Comment"] }}</td>
+    </tr>
+  {% endfor %}
+  </tbody>
+</table>
+<br>
+