docs(ses): Document environment lockdown options #2018
Conversation
packages/ses/docs/lockdown.md
Outdated
|
|
||
| In the absence of any of these options in lockdown arguments, lockdown will | ||
| attempt to read these from the Node.js `process.env` environment. | ||
| The corresponding environment variables are the same but in `UPPER_SNAKE_CASE`. | ||
| attempt to read these options from the corresponding Node.js `process.env` environment. |
There was a problem hiding this comment.
Might want to additionally explain, for those not familiar with this node feature, that for the start compartment these typically reflect *Nix environment variables in the context that the node process was launched from. Or just link to the @endo/env-options package.
packages/ses/docs/lockdown.md
Outdated
| The corresponding environment variables are the same but in `UPPER_SNAKE_CASE`. | ||
| attempt to read these options from the corresponding Node.js `process.env` environment. | ||
|
|
||
| | option | environment variable | | |
There was a problem hiding this comment.
Three column table looks weird without a heading for the third column. How about simply "notes"?
packages/ses/docs/lockdown.md
Outdated
| The `consoleTaming: 'safe'` setting replaces the global console with a tamed | ||
| console, and that tamed console is safe to endow to a guest `Compartment`. | ||
| Additionally, any errors created with the `assert` function or methods on its | ||
| namespace may have redacted details: information included in the error message | ||
| that is informative to a debugger and made invisible to an attacker. | ||
| The tamed console removes redactions and shows these details to the original | ||
| console. |
There was a problem hiding this comment.
New paragraph is great and was badly needed. Please also add a link to https://github.com/endojs/endo/blob/master/packages/ses/src/error/README.md
| Until we know otherwise, we should assume these are unsafe. Such a raw | ||
| `console` object should only be handled by very trustworthy code. |
There was a problem hiding this comment.
FYI
endo/packages/ses/src/lockdown.js
Lines 312 to 314 in 193e403
| throw new TypeError(); | ||
| }; |
There was a problem hiding this comment.
Too bad eslint doesn't run on "```js" blocks in .md files ;)
packages/ses/docs/lockdown.md
Outdated
| @@ -617,6 +709,15 @@ lockdown({ overrideTaming: 'min' }); // Minimal mitigations for purely modern co | |||
| lockdown({ overrideTaming: 'severe' }); // More severe legacy compat | |||
| ``` | |||
|
|
|||
| If `lockdown` receives no election for `stackFiltering`, it will | |||
There was a problem hiding this comment.
| If `lockdown` receives no election for `stackFiltering`, it will | |
| If `lockdown` receives no election for `overrideTaming`, it will |
Other similar cut/paste errors in this same position below. Please check them all.
kriskowal
force-pushed
the
kriskowal-lockdown-environment-options-1910
branch
from
a54fdaf to
a2d796a
Compare
Closes #1910
Description
This change adds documentation to the existing lockdown environment options.
Security Considerations
No impact on security except a reduction in obscurity.
Scaling Considerations
No code changes.
Documentation Considerations
Fills a void in documentation. The issue remains that this documentation is not easy to find.
Testing Considerations
No changes.
Compatibility Considerations
No effects.
Upgrade Considerations
No changes.