feat: Add support for custom guidance and appendices in HTML reports

[leonamagaya]

What does this PR do?

This PR adds support for customizable guidance and appendices content in Cloudsplaining HTML reports. Users can now provide their own HTML content files to customize the guidance and appendices sections of their reports.

Key features:

• Custom content files: Users can create custom-guidance.html and custom-appendices.html files in their working directory
• Automatic detection: The system automatically detects and loads custom content files when present
• Fallback behavior: Falls back to default content when custom files don't exist
• Navigation control: Empty custom files hide the corresponding navigation sections entirely
• Security: Proper HTML escaping prevents JavaScript injection vulnerabilities
• Flexible usage: Supports mixed scenarios (one custom file, one default)

How to use this feature

Use Case 1: Custom Guidance Content

# Create custom guidance with organization-specific instructions
cat > custom-guidance.html << EOF
<h1>Custom Security Guidelines</h1>
<h2>Remediation Process</h2>
<p>1. Review the identified policy violations</p>
<p>2. Follow internal approval process for policy changes</p>
<p>3. Contact security team for assistance</p>
<h2>Additional Resources</h2>
<p><a href="https://internal-wiki.com/security">Internal Security Documentation</a></p>
EOF

# Standard cloudsplaining workflow (unchanged)
cloudsplaining download
cloudsplaining scan --input-file default.json --output reports/

Result: Report shows your custom guidance content instead of default AWS guidance.

Use Case 2: Custom Appendices with Additional Resources

# Add custom appendices with relevant links and information
cat > custom-appendices.html << EOF
<h1>Additional Resources</h1>
<h2>Internal Documentation</h2>
<ul>
<li><a href="https://docs.internal.com/iam-policies">IAM Policy Standards</a></li>
<li><a href="https://docs.internal.com/security-review">Security Review Process</a></li>
</ul>
<h2>Contact Information</h2>
<p>Security Team: [email protected]</p>
<p>DevOps Team: [email protected]</p>
EOF

cloudsplaining scan --input-file default.json --output reports/

Result: Report shows custom appendices content instead of default AWS appendices

Use Case 3: Hide Sections Completely

# Hide both guidance and appendices sections
echo "" > custom-guidance.html
echo "" > custom-appendices.html

cloudsplaining scan --input-file default.json --output reports/

Result: No Guidance or Appendices tabs appear in the navigation

Use Case 4: Mixed Configuration

# Custom guidance, default appendices
cat > custom-guidance.html << EOF
<h1>Custom Remediation Steps</h1>
<p>Follow these steps to address policy issues...</p>
EOF
# Don't create custom-appendices.html

cloudsplaining scan --input-file default.json --output reports/

Result: Custom guidance tab + default AWS appendices tab

Use Case 5: Default Behavior (No Changes)

# Don't create any custom files - works exactly as before
cloudsplaining scan --input-file default.json --output reports/

Result: Standard AWS guidance and appendices content (existing behavior)

File Requirements

• Files must be named exactly custom-guidance.html and custom-appendices.html
• Files must be in the directory where you run the cloudsplaining scan command
• Files can contain any valid HTML content
• Empty files hide the corresponding navigation sections

What gif best describes this PR or how it makes you feel?

Completion checklist

• Additions and changes have unit tests
• The pull request has been appropriately labeled using the provided PR labels
• GitHub actions automation is passing (make test, make lint, make security-test, make test-js)
• If the UI contents or JavaScript files have been modified, generate a new example report:

[Copilot]

Pull Request Overview

This PR adds support for custom guidance and appendices content in Cloudsplaining HTML reports by allowing users to provide custom HTML files that override default content sections.

• Adds TemplateConfig class to detect and process custom HTML files (custom-guidance.html and custom-appendices.html)
• Implements conditional navigation visibility based on content availability
• Integrates custom content rendering in Vue.js components with proper HTML escaping

Reviewed Changes

Copilot reviewed 8 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/shared/test_template_config.py	Comprehensive test suite covering all template configuration scenarios
cloudsplaining/shared/template_config.py	Core logic for detecting, loading, and processing custom content files
cloudsplaining/output/template.html	JavaScript variable definitions for template configuration
cloudsplaining/output/src/views/Guidance.vue	Vue component updated to render custom or default guidance content
cloudsplaining/output/src/views/Appendices.vue	Vue component updated to render custom or default appendices content
cloudsplaining/output/src/routes/routes.js	Dynamic route registration based on navigation visibility flags
cloudsplaining/output/src/App.vue	Navigation menu updates with conditional visibility and code formatting
cloudsplaining/output/report.py	Integration of TemplateConfig into the report generation process

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[kmcquade]

Gave some feedback. Some additional requests:

1. In your PR description, can you give instructions on how others would use these changes? It seems like it does not affect any command line args, right? Only if you are wrapping Cloudsplaining as a library?
2. It would be great if you would include these changes in the documentation as well.

[kmcquade]

I see these two new chunk files. I haven't looked in a while, but I believe in the template.html we are specifically injecting index.js and chunk-vendors.js. Are these chunk files intended to be injected into the HTML template or should they be part of the chunk-vendors.js?

I want to make sure we aren't breaking anyone. I realize we don't have any Playwright tests to validate the html file works as expected, but you can test this by Installing the package from a different virtual environment.

# Remove those chunk files
# Navigate to a different directory
cd ../different-project
python3 -m venv venv
source venv/bin/activate
pip3 install /path/to/cloudsplaining/dev
# run cloudsplaining commands to generate a report
# view the report and see if there are errors

Can you let me know how that goes?

[kmcquade]

It looks like a lot of these changes are formatting changes that don't reflect functionality changes which makes it difficult to review. If possible, it would be great if you could revert changes that are only related to formatting.

[kmcquade]

Can you explain the rationale/approach here and any potential side effects?

[leonamagaya]

typeof window !== 'undefined' : prevents errors during server-side rendering or node.js environments where window doesn't exist.
window.show_guidance_nav === "True": checks if the python backend set this variable to true

The purpose is to conditionally add routes only only when the custom guidance or appendices should be shown.

The potential side effects:
This approach conditionally registers routes only when needed (potentially reducing bundle size), safely handles server-side rendering environments where window is undefined, and works reliably since the window.show_guidance_nav value is set once during report generation and never changes during the user session.

Alternatively I could move this logic to the Vue component level instead of the route level but in my humble opinion the current approach is cleaner for navigation.