Skip to content

Conversation

leonamagaya
Copy link

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?

image

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:

Copy link

Thanks for the contribution! Unfortunately we can't verify the commit author(s): Leona Magaya <l***@t***.com>. One possible solution is to add that email to your GitHub account. Alternatively you can change your commits to another email and force push the change. After getting your commits associated with your GitHub account, sign the Salesforce Inc. Contributor License Agreement and this Pull Request will be revalidated.

- 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
@leonamagaya leonamagaya force-pushed the feat/custom-guidance-and-appendices branch from 68f03cf to 68d9b92 Compare September 10, 2025 10:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant