Skip to content

JSON Schema

Results JSON Schema

When Cloudsplaining is run on an account using the download command, the results of the iam:GetAccountAuthorizationDetails API call and stores it in a JSON file. Then the scan command generates (1) The HTML report, and (2) a JSON file containing raw data about the results. This JSON data file is covered in this page.

Structure

The JSON data file contains these top-level keys:

  • groups
  • users
  • roles
  • aws_managed_policies
  • customer_managed_policies
  • inline_policies
  • exclusions
  • links

The final HTML file contains the JSON content above as a single global variable. This process is discussed on the Contributing/JavaScript documentation page.

By default, the report leverages the content of the SampleData.js file - unless the variable isLocal is set to false. Cloudsplaining does this automatically when the scan command is run. (This is just for background; don't worry about how this all works).

We do it this way so that the HTML report can leverage JavaScript that simply parses through JSON content. This way, we aren't building the HTML directly from Python, which gets messy very quickly.

Modifying the JSON data file contents

The above raises the question - if you want to expose more data in the JSON data file, how would you make those additions?

Step 1: Modify the Python

Well, first of all - you'd have to modify the Python that generates the data file. The JSON data is generated by the results property in the cloudsplaining.scan.authorization_details module in the AuthorizationDetails class here:

class AuthorizationDetails:
    """
    Represents the entire JSON file generated by the aws iam get-account-authorization-details command.
    """
    #...
    #...
    @property
    def results(self):
        """Get the new JSON format of the Principals data"""
        results = {
            "groups": self.group_detail_list.json,
            "users": self.user_detail_list.json,
            "roles": self.role_detail_list.json,
            "aws_managed_policies": self.policies.json_large_aws_managed,
            "customer_managed_policies": self.policies.json_large_customer_managed,
            "inline_policies": self.inline_policies,
            "exclusions": self.exclusions.config
        }
        return results

To add more data to the JSON data file, you'd first have to add the content there.

Step 2: Generate the example IAM data

Now we have to update the sampleData.js file so that it has the new JSON data in it. To do so, you can run the following script:

./utils/generate_example_iam_data.py

This will do the following:

  1. Updates utils/example-iam-data.json to contain the updated JSON contents and structure
  2. Updates cloudsplaining/output/src/sampleData.js

Now, if you want to view the latest report to make sure it works, you can just run:

npm install
npm serve

Step 3: Modify the JavaScript to parse through the latest additions to the Data JSON file

Follow the instructions on the JavaScript Contributions documentation to parse through the latest additions to the data JSON file.

Step 4: Don't forget to update the example report!

Don't forget to update the example report so it shows your latest updates, as discussed here.

./utils/generate_example_report.py

That will generate the example report, without having to go through the full scan.

Modifying the