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.

The level of detail is intentionally kept at a high level. Instead of describing specific technologies or deployment configurations, the focus is on presenting a holistic view of the platform. This includes explaining how the different components interact with each other and outlining the security measures that are in place. The goal is to give readers a clear understanding of how the platform is designed to operate securely and maintain its intended state.

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]

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

[claude]

Documentation Review

I've reviewed PR #16811 which adds an updated security whitepaper as markdown content. Overall, the content is well-structured and comprehensive. Here are my findings:

✅ Strengths

• Well-organized, thorough technical documentation
• Proper frontmatter with title, meta_desc, and layout
• Mermaid diagrams are properly formatted and supported
• Content follows a logical flow from architecture through cryptography to operations
• File ends with a proper newline

Issues Found

1. Grammar: Missing article (line 25)

Line 25 has awkward phrasing:

On its core service layer, the cloud service provides RESTful APIs for all platform operations, while specialized

Should be:

At its core service layer, the cloud service provides RESTful APIs for all platform operations, while specialized

Or better yet, simplify:

The cloud service's core service layer provides RESTful APIs for all platform operations, while specialized

2. Inconsistent terminology (throughout document)

The document switches between "Pulumi Cloud platform," "the platform," "Pulumi platform," and "Pulumi Cloud." For consistency and clarity, I recommend:

• Use "Pulumi Cloud" when specifically referring to the managed service
• Use "Pulumi platform" when referring to the entire system (client + service)
• Be consistent with the choice throughout

This is particularly noticeable in:

• Line 11: "Pulumi Cloud platform"
• Line 20: "Pulumi platform"
• Line 486: "Pulumi Cloud platform"

3. Index page update needed (content/security/_index.md:12)

The link text on the index page needs updating for clarity:

For more details on Pulumi's platform architecture and security practices, please read our [security whitepaper](/security/pulumi-cloud-security-whitepaper).

Should specify that it's now an embedded page, not a PDF:

For more details on Pulumi's platform architecture and security practices, read our [security whitepaper](/security/pulumi-cloud-security-whitepaper).

(Minor: removed "please" for conciseness per style guide preference for direct language)

4. SCSS change not explained (theme/src/scss/_code.scss:50)

The diff shows a change to line 50 in the SCSS file, but the change isn't visible in the diff output. This change should be verified and explained in the PR description or commit message if it's intentional.

5. PDF file handling

The PR shows the PDF file in the files list but with 0 additions/deletions. Please clarify:

• Is the PDF file being deleted?
• Should an alias redirect be added from the old PDF URL to the new markdown page?

Per AGENTS.md, when files are deleted or moved, redirects should be created. If users have bookmarked /security/pulumi-cloud-security-whitepaper.pdf, they should be redirected to the new markdown page.

Recommendations

1. Add redirect for PDF URL: Add an S3 redirect in /scripts/redirects/ to redirect the old PDF URL to the new markdown page
2. Consider adding last updated date to frontmatter: Since the document explicitly states "Last updated: December 2025" in the content, consider adding a date field to the frontmatter for consistency with Hugo conventions
3. Verify all technical claims: Since this is a security whitepaper, ensure all technical details (encryption algorithms, compliance certifications, etc.) are accurate and current

Style Compliance

✅ Proper heading hierarchy (H1 in title, H2+ in sentence case)
✅ File ends with newline
✅ Mermaid diagrams properly formatted
✅ Proper frontmatter structure
✅ No trailing spaces detected in diff

---

Great work on converting this important document to markdown format! The embedded approach will make it easier to maintain and update. If you'd like me to help with any of the suggestions above or need additional review after making changes, feel free to mention me (@claude).

[pulumi-bot]

Your site preview for commit f80346f is ready! 🎉

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

[pulumi-bot]

Your site preview for commit 1045f9b is ready! 🎉

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

[jdavredbeard]

just making sure - fully managed cloud deployments means the Pulumi Cloud PaaS as deployed by Pulumi in our internal AWS account? distinct cloud provider tenants means for ex. AWS accounts?

[borisschlosser]

Exactly. Yes the idea is to give a more high level view of the overall platform without mentioning exact implementation/deployment details.

[jdavredbeard]

on Friday it will include attribute based access I think? but we can update this

[borisschlosser]

Yes as this is now available as markdown it will be much easier to update it accordingly.

[jdavredbeard]

Workflow integration refers to the Deployments platform feature, yes? Should we be explicit about that, or are we being more general on purpose? I kind of prefer workflow integration as a feature name personally, but that is not what it is called now, and it is a little confusing since you also mention Deployment Orchestration above, which I think just refers to running core pulumi operations like update without Deployment runners.

[borisschlosser]

Yeah that's confusing. I merged the Deployment orchestration and Workflow integration sections. So this should basically represent the architecture of the whole Deployments feature.

[jdavredbeard]

You mention AI-powered assistance in the diagram above - is that not a core feature?

[borisschlosser]

It is :) Added a paragraph.

[jdavredbeard]

what does provider-managed mean in the context of encryption services?

[borisschlosser]

Provider managed means that the provider of the platform needs to maintain an encryption service which is responsible to encrypt data at rest. In case of Pulumi Cloud we are the provider and we are using AWS KMS to encrypt data at rest. This might defer for self-hosted installations.

[jdavredbeard]

I think command-line interface and the client are both referring to the CLI but the client is an overloaded enough term that I had to read this twice

[borisschlosser]

Agreed and changed

[jdavredbeard]

the randomly generated initialization vector is a cool detail

[jdavredbeard]

In general this version seems like it is going for a more cloud service agnostic description than the previous one, which could be valuable as a additional layer of description, but without the specific service implementation details, it makes it seem like we might be hiding the actual implementation on purpose, which seems counter to the intent of a security whitepaper, where we are trying to build confidence by being transparent. I also miss the color diagrams of the cloud architecture with specific AWS services from the previous version.

[borisschlosser]

In general this version seems like it is going for a more cloud service agnostic description than the previous one, which could be valuable as a additional layer of description, but without the specific service implementation details, it makes it seem like we might be hiding the actual implementation on purpose, which seems counter to the intent of a security whitepaper, where we are trying to build confidence by being transparent. I also miss the color diagrams of the cloud architecture with specific AWS services from the previous version.

Regarding the level of detail I have updated the PR description.

The level of detail is intentionally kept at a high level. Instead of describing specific technologies or deployment configurations, the focus is on presenting a holistic view of the platform. This includes explaining how the different components interact with each other and outlining the security measures that are in place. The goal is to give readers a clear understanding of how the platform is designed to operate securely and maintain its intended state.

[pulumi-bot]

Your site preview for commit 12941dd is ready! 🎉

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