feat: Add custom guidance and appendices support

- Add TemplateConfig class to detect and process custom HTML files
- Support custom-guidance.html and custom-appendices.html in project root
- Implement dynamic navigation with conditional tab visibility
- Add Vue components for custom content rendering with v-html
- Include comprehensive test coverage for all scenarios
- Update documentation with usage examples and behavior guide

Author: Leona Magaya

README.md

@@ -332,6 +332,47 @@ cloudsplaining scan-multi-account \
 
 > Note that if you run the above without the `--profile` flag, it will execute in the standard [AWS Credentials order of precedence](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default) (i.e., Environment variables, credentials profiles, ECS container credentials, then finally EC2 Instance Profile credentials). 
 
+## Custom Guidance and Appendices
+
+Cloudsplaining supports customizing the Guidance and Appendices sections of the HTML report to include organization-specific security recommendations and documentation.
+
+### How It Works
+
+Place HTML files in your project root directory:
+
+- `custom-guidance.html` - Custom security guidance content
+- `custom-appendices.html` - Custom appendices content
+
+### Behavior
+
+- **Files don't exist**: Shows default AWS security advice
+- **Files exist with content**: Shows your custom HTML content
+- **Files exist but are empty**: Hides the tabs entirely
+- **Mixed configuration**: Each tab works independently
+
+### Example Usage
+
+```bash
+# Create custom guidance
+echo '<h1>Company Security Guidelines</h1>
+<p>Follow these organization-specific steps:</p>
+<ul>
+  <li>Review with security team</li>
+  <li>Document in JIRA ticket</li>
+  <li>Get approval before remediation</li>
+</ul>' > custom-guidance.html
+
+# Create custom appendices  
+echo '<h1>Internal Resources</h1>
+<p>Additional company resources:</p>
+<ul>
+  <li><a href="https://internal.company.com/security">Security Portal</a></li>
+  <li><a href="https://wiki.company.com/iam">IAM Best Practices</a></li>
+</ul>' > custom-appendices.html
+```
+
+# Generate report with custom content
+cloudsplaining scan --input-file account-data.json --output reports/
 
 ## Cheatsheet
 

cloudsplaining/output/dist/js/index.js

@@ -11,6 +11,7 @@
 from jinja2 import Environment, FileSystemLoader
 
 from cloudsplaining.bin.version import __version__
+from cloudsplaining.shared.template_config import TemplateConfig
 
 app_bundle_path = os.path.join(os.path.dirname(__file__), "dist", "js", "index.js")
 
@@ -30,6 +31,7 @@ def __init__(
         self.report_generated_time = datetime.datetime.now().strftime("%Y-%m-%d")
         self.minimize = minimize
         self.results = f"var iam_data = {json.dumps(results, default=str)}"
+        self.template_config = TemplateConfig()
 
     @property
     def app_bundle(self) -> str:
@@ -73,6 +75,10 @@ def get_html_report(self) -> str:
             account_name=self.account_name,
             report_generated_time=str(self.report_generated_time),
             cloudsplaining_version=__version__,
+            guidance_content=self.template_config.guidance_content,
+            appendices_content=self.template_config.appendices_content,
+            show_guidance_nav=self.template_config.show_guidance_nav,
+            show_appendices_nav=self.template_config.show_appendices_nav,
         )
         template_path = os.path.dirname(__file__)
         env = Environment(loader=FileSystemLoader(template_path))  # noqa: S701

cloudsplaining/output/report.py

@@ -1,174 +1,197 @@
 <template>
     <div id="main">
         <b-navbar toggleable="md" variant="faded">
-            <b-navbar-brand to="/summary">
-                Cloudsplaining
-            </b-navbar-brand>
+            <b-navbar-brand to="/summary"> Cloudsplaining </b-navbar-brand>
             <b-navbar-toggle target="nav-collapse"></b-navbar-toggle>
 
             <b-collapse id="nav-collapse" is-nav>
                 <b-navbar-nav>
-                    <b-nav-item to="/customer-policies">Customer Policies</b-nav-item>
-                    <b-nav-item to="/inline-policies">Inline Policies</b-nav-item>
+                    <b-nav-item to="/customer-policies"
+                        >Customer Policies</b-nav-item
+                    >
+                    <b-nav-item to="/inline-policies"
+                        >Inline Policies</b-nav-item
+                    >
                     <b-nav-item to="/aws-policies">AWS Policies</b-nav-item>
                     <b-nav-item to="/iam-principals">IAM Principals</b-nav-item>
-                    <b-nav-item to="/guidance">Guidance</b-nav-item>
-                    <b-nav-item to="/appendices">Appendices</b-nav-item>
+                    <b-nav-item v-if="show_guidance_nav" to="/guidance"
+                        >Guidance</b-nav-item
+                    >
+                    <b-nav-item v-if="show_appendices_nav" to="/appendices"
+                        >Appendices</b-nav-item
+                    >
                     <!-- <b-nav-item to="/task-table">Task Table Demo</b-nav-item> -->
                 </b-navbar-nav>
                 <b-navbar-nav class="ml-auto">
-                    <b-nav-text><strong>Account ID:</strong> {{ account_id }} | <strong>Account Name:</strong> {{ account_name }}</b-nav-text>
+                    <b-nav-text
+                        ><strong>Account ID:</strong> {{ account_id }} |
+                        <strong>Account Name:</strong>
+                        {{ account_name }}</b-nav-text
+                    >
                 </b-navbar-nav>
             </b-collapse>
         </b-navbar>
 
         <b-container class="mt-3 pb-3 report">
             <b-tabs nav-class="d-none">
                 <router-view />
-               <!-- <b-tab key="task-table">-->
-<!--                    <br>-->
-<!--                    <h3>Tasks (demo WIP)</h3>-->
-<!--                    <br>-->
-<!--&lt;!&ndash;                    <h3>Customer-Managed Policies</h3>&ndash;&gt;-->
-<!--&lt;!&ndash;                    <TaskTable managedBy="Customer" v-bind:items_mapping="getTaskTableMapping('Customer')"/>&ndash;&gt;-->
-<!--&lt;!&ndash;                    <br>&ndash;&gt;-->
-<!--                    &lt;!&ndash;TODO: Figure out the overlap issue where the two tables results in a double info field in Customer policies&ndash;&gt;-->
-<!--                    <h3>AWS-Managed Policies</h3>-->
-<!--                    <TaskTable managedBy="AWS" v-bind:items_mapping="getTaskTableMapping('AWS')"/>-->
-<!--                    &lt;!&ndash;TODO: Task table for Inline Policies&ndash;&gt;-->
-<!--&lt;!&ndash;                    <h3>Inline Policies</h3>&ndash;&gt;-->
-<!--&lt;!&ndash;                    <TaskTable v-bind:policyNameMapping="getInlinePolicyNameMapping()"/>&ndash;&gt;-->
-<!--                </b-tab> -->
+                <!-- <b-tab key="task-table">-->
+                <!--                    <br>-->
+                <!--                    <h3>Tasks (demo WIP)</h3>-->
+                <!--                    <br>-->
+                <!--&lt;!&ndash;                    <h3>Customer-Managed Policies</h3>&ndash;&gt;-->
+                <!--&lt;!&ndash;                    <TaskTable managedBy="Customer" v-bind:items_mapping="getTaskTableMapping('Customer')"/>&ndash;&gt;-->
+                <!--&lt;!&ndash;                    <br>&ndash;&gt;-->
+                <!--                    &lt;!&ndash;TODO: Figure out the overlap issue where the two tables results in a double info field in Customer policies&ndash;&gt;-->
+                <!--                    <h3>AWS-Managed Policies</h3>-->
+                <!--                    <TaskTable managedBy="AWS" v-bind:items_mapping="getTaskTableMapping('AWS')"/>-->
+                <!--                    &lt;!&ndash;TODO: Task table for Inline Policies&ndash;&gt;-->
+                <!--&lt;!&ndash;                    <h3>Inline Policies</h3>&ndash;&gt;-->
+                <!--&lt;!&ndash;                    <TaskTable v-bind:policyNameMapping="getInlinePolicyNameMapping()"/>&ndash;&gt;-->
+                <!--                </b-tab> -->
             </b-tabs>
         </b-container>
         <b-container>
             <b-row class="mt-5">
                 <b-col class="text-center text-muted">
                     Report Generated: {{ report_generated_time }} &diamond;
                     Cloudsplaining version:
-                    <b-link href="https://github.com/salesforce/cloudsplaining">{{ cloudsplaining_version }}</b-link>
+                    <b-link
+                        href="https://github.com/salesforce/cloudsplaining"
+                        >{{ cloudsplaining_version }}</b-link
+                    >
                 </b-col>
             </b-row>
         </b-container>
     </div>
 </template>
 
 <script>
-    const managedPoliciesUtil = require('./util/managed-policies');
-    const inlinePoliciesUtil = require('./util/inline-policies');
-    const taskTableUtil = require('./util/task-table');
-    const sampleData = require('./sampleData');
+const managedPoliciesUtil = require("./util/managed-policies");
+const inlinePoliciesUtil = require("./util/inline-policies");
+const taskTableUtil = require("./util/task-table");
+const sampleData = require("./sampleData");
 
-    console.log(`process.env.NODE_ENV: ${process.env.NODE_ENV}`)
+console.log(`process.env.NODE_ENV: ${process.env.NODE_ENV}`);
 
-    // This conditionally loads the local sample data if you are developing, but not if you are viewing the report
+// This conditionally loads the local sample data if you are developing, but not if you are viewing the report
 
+// eslint-disable-next-line no-undef
+if (process.env.NODE_ENV === "development" || isLocalExample === true) {
     // eslint-disable-next-line no-undef
-    if ((process.env.NODE_ENV === "development") || (isLocalExample === true)) {
-        // eslint-disable-next-line no-undef
-        console.log(`isLocalExample is set to: ${isLocalExample}`)
-        console.log(`process.env.NODE_ENV: ${process.env.NODE_ENV}`)
-        console.log(`Note: a report generated with the Python template will not have isLocalExample set to True, because that uses a separate template.html file, which has isLocalExample set to False.`)
-        // eslint-disable-next-line no-unused-vars,no-undef
-        iam_data = sampleData.sample_iam_data;
-        // eslint-disable-next-line no-undef
-        console.log(`IAM Data keys inside the development if statement: ${Object.keys(iam_data)}`);
-        // eslint-disable-next-line no-unused-vars,no-undef
-        account_id = "12345678912";
-        // eslint-disable-next-line no-unused-vars,no-undef
-        account_name = "example";
-        // eslint-disable-next-line no-unused-vars,no-undef
-        report_generated_time = "2020-09-01";
-        // eslint-disable-next-line no-unused-vars,no-undef
-        cloudsplaining_version = "0.2.2";
-    }
-    else {
-        // eslint-disable-next-line no-undef
-        console.log(`isLocalExample is set to: ${isLocalExample}`)
-    }
+    console.log(`isLocalExample is set to: ${isLocalExample}`);
+    console.log(`process.env.NODE_ENV: ${process.env.NODE_ENV}`);
+    console.log(
+        `Note: a report generated with the Python template will not have isLocalExample set to True, because that uses a separate template.html file, which has isLocalExample set to False.`
+    );
+    // eslint-disable-next-line no-unused-vars,no-undef
+    iam_data = sampleData.sample_iam_data;
 
+    console.log(
+        `IAM Data keys inside the development if statement: ${Object.keys(
+            // eslint-disable-next-line no-undef
+            iam_data
+        )}`
+    );
+    // eslint-disable-next-line no-unused-vars,no-undef
+    account_id = "12345678912";
+    // eslint-disable-next-line no-unused-vars,no-undef
+    account_name = "example";
+    // eslint-disable-next-line no-unused-vars,no-undef
+    report_generated_time = "2020-09-01";
+    // eslint-disable-next-line no-unused-vars,no-undef
+    cloudsplaining_version = "0.2.2";
+} else {
     // eslint-disable-next-line no-undef
-    console.log(`IAM Data keys outside of the NODE_ENV if statements: ${Object.keys(iam_data)}`);
+    console.log(`isLocalExample is set to: ${isLocalExample}`);
+}
 
-
-    function getManagedPolicyNameMapping(managedBy) {
+console.log(
+    `IAM Data keys outside of the NODE_ENV if statements: ${Object.keys(
         // eslint-disable-next-line no-undef
-        return managedPoliciesUtil.getManagedPolicyNameMapping(iam_data, managedBy)
-    }
+        iam_data
+    )}`
+);
 
-    function getInlinePolicyNameMapping() {
-        // eslint-disable-next-line no-undef
-        return inlinePoliciesUtil.getInlinePolicyNameMapping(iam_data)
-    }
+function getManagedPolicyNameMapping(managedBy) {
+    // eslint-disable-next-line no-undef
+    return managedPoliciesUtil.getManagedPolicyNameMapping(iam_data, managedBy);
+}
 
-    function getTaskTableMapping(managedBy) {
-        // eslint-disable-next-line no-undef
-        return taskTableUtil.getTaskTableMapping(iam_data, managedBy)
-    }
+function getInlinePolicyNameMapping() {
+    // eslint-disable-next-line no-undef
+    return inlinePoliciesUtil.getInlinePolicyNameMapping(iam_data);
+}
 
+function getTaskTableMapping(managedBy) {
+    // eslint-disable-next-line no-undef
+    return taskTableUtil.getTaskTableMapping(iam_data, managedBy);
+}
 
-    export default {
-        name: 'App',
-        mounted: function()
-        {
-            // Workaround for handling anchors when vue-router is in hash mode
-            // https://stackoverflow.com/a/45206192
-            setTimeout(() => this.scrollFix(this.$route.hash), 1);
+export default {
+    name: "App",
+    mounted: function () {
+        // Workaround for handling anchors when vue-router is in hash mode
+        // https://stackoverflow.com/a/45206192
+        setTimeout(() => this.scrollFix(this.$route.hash), 1);
+    },
+    data() {
+        return {
+            // eslint-disable-next-line no-undef
+            sharedState: iam_data,
+            // eslint-disable-next-line no-undef
+            account_id: account_id,
+            // eslint-disable-next-line no-undef
+            account_name: account_name,
+            // eslint-disable-next-line no-undef
+            report_generated_time: report_generated_time,
+            // eslint-disable-next-line no-undef
+            cloudsplaining_version: cloudsplaining_version,
+            // eslint-disable-next-line no-undef
+            show_guidance_nav: show_guidance_nav === "True",
+            // eslint-disable-next-line no-undef
+            show_appendices_nav: show_appendices_nav === "True",
+        };
+    },
+    computed: {
+        iam_data() {
+            return this.sharedState;
+        },
+    },
+    methods: {
+        getManagedPolicyNameMapping: function (managedBy) {
+            return getManagedPolicyNameMapping(managedBy);
         },
-        data() {
-            return {
-                // eslint-disable-next-line no-undef
-                sharedState: iam_data,
-                // eslint-disable-next-line no-undef
-                account_id: account_id,
-                // eslint-disable-next-line no-undef
-                account_name: account_name,
-                // eslint-disable-next-line no-undef
-                report_generated_time: report_generated_time,
-                // eslint-disable-next-line no-undef
-                cloudsplaining_version: cloudsplaining_version,
-            };
+        getInlinePolicyNameMapping: function () {
+            return getInlinePolicyNameMapping();
         },
-        computed: {
-            iam_data() {
-                return this.sharedState
-            }
+        getTaskTableMapping: function (managedBy) {
+            return getTaskTableMapping(managedBy);
         },
-        methods: {
-            getManagedPolicyNameMapping: function (managedBy) {
-                return getManagedPolicyNameMapping(managedBy)
-            },
-            getInlinePolicyNameMapping: function () {
-                return getInlinePolicyNameMapping()
-            },
-            getTaskTableMapping: function (managedBy) {
-                return getTaskTableMapping(managedBy)
-            },
-            scrollFix: function(hashbang)
-            {
-                location.hash = hashbang;
-            }
+        scrollFix: function (hashbang) {
+            location.hash = hashbang;
         },
-        provide() {
-            return {
-                iam_data: this.iam_data,
-                getManagedPolicyNameMapping: this.getManagedPolicyNameMapping,
-                getInlinePolicyNameMapping: this.getInlinePolicyNameMapping,
-            }
-        }
-    }
+    },
+    provide() {
+        return {
+            iam_data: this.iam_data,
+            getManagedPolicyNameMapping: this.getManagedPolicyNameMapping,
+            getInlinePolicyNameMapping: this.getInlinePolicyNameMapping,
+        };
+    },
+};
 </script>
 
 <style>
-    #main {
-        font-family: Avenir, Helvetica, Arial, sans-serif;
-        -webkit-font-smoothing: antialiased;
-        -moz-osx-font-smoothing: grayscale;
-        text-align: left;
-        color: #2c3e50;
-    }
+#main {
+    font-family: Avenir, Helvetica, Arial, sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-align: left;
+    color: #2c3e50;
+}
 
-    .router-link-exact-active {
-        font-weight: bold;
-    }
+.router-link-exact-active {
+    font-weight: bold;
+}
 </style>