Pulumi Platform Security Whitepaper

[borisschlosser]

This PR adds an updated version of the Pulumi platform security whitepaper. We are now embedding the whitepaper as markdown into the website directly instead of having a separate pdf.

Resolves: #16654

[claude]

Documentation Review

Thank you for updating the Pulumi Platform Security Whitepaper! This is a comprehensive document that provides detailed technical information about the platform's security architecture. I've reviewed the changes and have some feedback on style and content.

Critical Issues

1. Missing comma on line 47

The sentence "In fully managed cloud deployments the platform is deployed..." is missing a comma after the introductory phrase.

In fully managed cloud deployments, the platform is deployed into distinct cloud provider tenants and virtual private

2. Missing article on line 403

Line 403: "demonstrates mature approach" should be "demonstrates a mature approach"

The separation of key management responsibilities through hierarchical key architectures, support for customer-managed
encryption keys, and cryptographic binding between encryption layers demonstrates a mature approach to data protection.

Style and Clarity Concerns

3. Overly complex sentence structure throughout

While this is a technical whitepaper, many sentences are extremely long and complex, making them difficult to parse. The Google Developer Documentation Style Guide (which this repo falls back to) recommends shorter, clearer sentences. Several examples:

• Lines 10-13: 58-word sentence about the platform
• Lines 19-23: 48-word sentence about cloud service architecture
• Lines 125-129: 54-word sentence about key hierarchy
• Lines 274-278: 60-word sentence about metrics collection

Consider breaking these into shorter, more digestible sentences. For example, lines 10-13 could be split:

The Pulumi Cloud platform represents a comprehensive infrastructure-as-code delivery system designed to enable
organizations to define, deploy, and manage cloud infrastructure through declarative programming interfaces. This
document provides a detailed technical overview of the platform's architecture, security mechanisms, and operational
commitments. It is intended for engineering and security audiences evaluating the system's design and security posture.

4. Inconsistent terminology: "application programming interface" vs "API"

Throughout the document, you spell out "application programming interface" in full rather than using the widely-known acronym "API". This makes the text unnecessarily verbose. Lines 26, 52, 60, 66, 116, etc. all use the full form. Per the style guide, widely known acronyms like API don't need expansion. Consider using "API" throughout for better readability.

5. Passive voice usage

Several sections use passive voice when active voice would be clearer:

• Line 81: "The database is deployed" → "We deploy the database"
• Line 86: "is stored" → "stores"
• Line 93: "are stored" → "store"

Per the documentation style guide, avoid passive voice for clarity.

6. Meta description length

Line 3: The meta description "A whitepaper of security topics and how they relate to the Pulumi Platform." could be more descriptive and SEO-friendly. Consider: "Technical whitepaper covering Pulumi platform architecture, cryptographic security, operational commitments, and SOC 2 Type II compliance."

7. Missing trailing newline

The file should end with a trailing newline after line 411 (per AGENTS.md requirement that all new files end with a newline).

Content Observations

8. Update date accuracy

Line 6 states "Last updated: December 2025" - please verify this is the intended date. At the time of this review, it's December 2025, so this appears correct if the intent is to reflect when this version was finalized.

9. Index page updates

The changes to content/security/_index.md look good. The updated language is more concise and the link now points to the markdown version rather than the PDF.

10. Moved file handling

The PR shows that pulumi-cloud-security-whitepaper.pdf is being deleted (0 additions/deletions). Per AGENTS.md requirements for moved/deleted files:

• Since this is a different format (PDF → Markdown), you should verify whether a redirect is needed from /security/pulumi-cloud-security-whitepaper.pdf to /security/pulumi-cloud-security-whitepaper
• This ensures external links to the PDF continue to work

Summary

This is a thorough and well-structured security whitepaper. The main issues are:

• Two grammar errors (missing comma and article)
• Very long, complex sentences that reduce readability
• Inconsistent use of "application programming interface" instead of "API"
• Missing trailing newline

The content itself is comprehensive and appropriate for the technical/security audience. Once the style issues are addressed, this will be an excellent resource for customers evaluating Pulumi's security posture.

---

Mention me (@claude) if you'd like me to help with any edits or if you want additional review after making changes!

[pulumi-bot]

Your site preview for commit 8fb53ff is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16811-8fb53fff.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit a4caf00 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16811-a4caf009.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit fded8ba is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16811-fded8bae.s3-website.us-west-2.amazonaws.com.

[tehsis]

The diagram is not rendered in http://www-testing-pulumi-docs-origin-pr-16811-8fb53fff.s3-website.us-west-2.amazonaws.com/security/pulumi-cloud-security-whitepaper/

[tehsis]

Content looks great, I'd approve it grammatically but might need a review from someone with more experience 👍 good job!