Add threat model by bioball · Pull Request #133 · apple/pkl-lang.org

bioball · 2026-06-03T22:57:02Z

No description provided.

HT154 · 2026-06-03T23:19:27Z

+PklProject.deps.json:: The dependency list, generated by `pkl project resolve`.
+Contains resolved versions and SHA-256 checksums for all declared package dependencies.
+
+Root directory:: A filesystem boundary configured via `--root-dir` that restricts `file:` reads to files within that path.


This affects imports and jar:file: URIs as well.

It doesn't affect: multiple file output from the CLI, package caching, loading settings.pkl, and external/custom readers. Did I miss anything?

Also doesn't affect loading PklProject, PklProject.deps.json. But these are also behaviors of the CLI specifically, not the language runtime.

HT154 · 2026-06-04T00:01:43Z

+
+== Threats
+
+=== Language Runtime


I think this is missing mention of DoS attacks and the use of timeouts as mitigation.

I don't think timeouts would really address this problem; you can still write a program that exhausts CPU/memory resources before a timeout hits.

Pkl would need flags for CPU/memory bounds, which we ideally should have.

HT154 · 2026-06-04T00:08:22Z

 Security vulnerabilities may be reported on the link:https://security.apple.com/submit[Report a vulnerability] form.
 When submitting a vulnerability, select "Apple Devices and Software" as the affected platform, and "Open Source" as the affected area.
+
+If you are not certain if something counts as a security vulnerability, you can review our xref:threat-model.adoc[threat model].


Hmm it might be good to explicitly call out up front that reports relying on evaluating untrusted code are only valid if Pkl's sandbox is bypassed and that overly broad (or default) evaluator settings are not considered a vulnerability.

HT154 · 2026-06-04T00:10:55Z

+
+Insecure Evaluator Client configurations::
+
+Users who configure overly broad evaluator permissions while executing un-trusted Pkl code.


Suggested change

Users who configure overly broad evaluator permissions while executing un-trusted Pkl code.

Overly broad evaluator permissions while executing un-trusted Pkl code that can result in compromise.

"User" here is referring to one of the external actors in the section above; it's to distinguish from, say, our language binding configures the evaluator insecurely which would be in-scope.

HT154 · 2026-06-04T00:14:00Z

+The Language Runtime enforces I/O permissions set by the Evaluator Client before evaluation begins.
+No Pkl code can modify these settings at runtime.


Might be worth noting that evaluators setting may be set via settings.pkl and/or PklProject so these files must be trusted or restricted as well. Probably worth calling out --no-project/--omit-project-settings and the override behavior of evaluator settings.

madrob

Non-blocking thoughts.

madrob · 2026-06-03T23:50:13Z

+==== Package Integrity
+
+When importing a package, the runtime verifies the package's contents against a SHA-256 checksum declared in the project's dependency list (`PklProject.deps.json`).
+This verification is independent of which server served the package, providing integrity guarantees even if the package server is compromised or the connection is intercepted.


This could also cover the local cache, in addition to remote servers.

The local cache is trusted and their contents aren't verified; attacks that require that an attacker have write permissions to the filesystem is considered out-of-scope.

madrob · 2026-06-03T23:51:19Z

+
+=== Package Resolution
+
+==== Tampered Package


Not sure if this belongs here or in supply chain, but we should call out that we do not offer protection against typo-squatting. Maybe in the future we can build a system to do that.

WRT building a system that prevents typosquatting: that's currently not a goal; we don't intend on maintaining a package registry anytime soon.

madrob · 2026-06-03T23:53:36Z

+* Pkl cannot perform I/O outside what is explicitly allowed.
+* Pkl code cannot modify or exceed the permissions established by the Evaluator Client.
+* Pkl cannot execute arbitrary system commands or load native code.
+* Pkl will run to completion, or time out.


Do we consider whatever the Pkl equivalent of adversarial regular expressions or ReDoS out of scope? Maybe a good example.

Mmm I think that ReDoS is out of scope; guards against DoS attacks would happen via resource limit flags (CPU and memory) if/once we have them.

Open to opinions here though.

madrob · 2026-06-03T23:55:45Z

+If the import URI does not include a SHA-256 checksum segment, the runtime performs no integrity verification and Pkl code within the tampered package is evaluated.
+
+NOTE: Package imports that include a checksum in the URI are verified against the declared hash.
+Direct imports without a checksum (e.g., `package://example.com/pkg@1.0.0#/mod.pkl`) are not verified.


This probably deserves its own item on the list, feels like a big deal.

Can you clarify? This is already its own item?

madrob · 2026-06-03T23:57:13Z

@@ -0,0 +1,392 @@
+= Threat Model


Add a version and date so that users can identify how recently reviewed this was.

Added a "last edited" date. Is the version useful? Can the edited date serve as the version?

Co-authored-by: Jen Basch <jbasch94@gmail.com>

stackoverflow · 2026-06-04T09:14:15Z

+
+[source,pkl]
+----
+import "package://example.com/pkg@1.0.0#/myModule.pkl"


nit: I'd add another example showing an import that does verify package integrity.

stackoverflow · 2026-06-04T09:18:46Z

+
+* Pkl cannot perform I/O outside what is explicitly allowed.
+* Pkl code cannot modify or exceed the permissions established by the Evaluator Client.
+* Pkl cannot execute arbitrary system commands or load native code.


Teechnically, due to external readers, Pkl can execute arbitrary code. But this is explained in other parts of this doc, so it's probably fine to not point this out here.

stackoverflow · 2026-06-04T09:35:31Z

+Package imports that include a checksum in the URI are verified against the declared hash.
+Direct imports without a checksum (e.g., `package://example.com/pkg@1.0.0#/mod.pkl`) are not verified.


This can also happen with regular project imports, not only direct package imports.
If the cache does not contain package X and an attacker tampered with it, Pkl will download the malicious package and cache it locally.

The PklProject.deps.json file guards against this; it includes the checksum of all dependencies and verifies them when downloading.

It protects you from a package version you already know about being tampered. It doesn't protect you from a package version being tampered before you store the checksum.

Yeah that's the "trust on first use" policy; definitely worth mentioning.

stackoverflow · 2026-06-04T09:39:04Z

+Users whose package imports do not include checksums would fetch and execute malicious packages without any verification failure.
+
+*Attacker:* Remote Attacker; Network Attacker +
+*Violates:* _pkg.pkl-lang.org only redirects to official Pkl-hosted content_; _Imported package dependencies are authentic_


_pkg.pkl-lang.org only redirects to official Pkl-hosted content_ is not in the Security Goals.

Ah yeah, I had that initially but got rid of it.

Co-authored-by: Islon Scherer <islonscherer@gmail.com>

Add threat model

0fcedfc

bioball force-pushed the threat-model branch from 2d69659 to 0fcedfc Compare June 3, 2026 23:00

HT154 reviewed Jun 4, 2026

View reviewed changes

madrob reviewed Jun 4, 2026

View reviewed changes

bioball and others added 5 commits June 3, 2026 21:11

Apply suggestions from code review

28161a6

Co-authored-by: Jen Basch <jbasch94@gmail.com>

Apply suggestion from @HT154

d562f04

Co-authored-by: Jen Basch <jbasch94@gmail.com>

Updates

c2297a9

Add resource exhaustion section

98a72bb

Move note about cpu/memory sandbox to threat, add cache poisoning threat

3c31c83

stackoverflow approved these changes Jun 4, 2026

View reviewed changes

Apply suggestions from code review

97fb694

Co-authored-by: Islon Scherer <islonscherer@gmail.com>


		Insecure Evaluator Client configurations::

		Users who configure overly broad evaluator permissions while executing un-trusted Pkl code.

	Users who configure overly broad evaluator permissions while executing un-trusted Pkl code.
	Overly broad evaluator permissions while executing un-trusted Pkl code that can result in compromise.

		The Language Runtime enforces I/O permissions set by the Evaluator Client before evaluation begins.
		No Pkl code can modify these settings at runtime.

		Package imports that include a checksum in the URI are verified against the declared hash.
		Direct imports without a checksum (e.g., `package://example.com/pkg@1.0.0#/mod.pkl`) are not verified.

Conversation

bioball commented Jun 3, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bioball Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bioball Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

madrob left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bioball Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

bioball Jun 4, 2026 •

edited

Loading

bioball Jun 4, 2026 •

edited

Loading

bioball Jun 4, 2026 •

edited

Loading