You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/guides/webpack.md
+10-17Lines changed: 10 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,16 +3,10 @@ title: 'lavamoat and webpack'
3
3
description: 'A user guide for adding LavaMoat protections to a webpack bundle'
4
4
---
5
5
6
-
TODO: make it more like a guide and less like just a readme.
7
-
8
-
LavaMoat Webpack Plugin wraps each module in the bundle in a [SES Compartment](https://github.com/endojs/endo/tree/master/packages/ses#compartment) and enforces a Policy independently per package.
9
-
10
-
:::Note[Beta]
11
-
LavaMoat Webpack plugin is currently in [Open Beta](https://github.com/LavaMoat/LavaMoat/discussions/723). It's pretty stable at this point, but breaking changes may still happen.
12
-
:::
6
+
LavaMoat Webpack Plugin wraps each module in the bundle in a [Compartment](https://hardenedjs.org/#compartment) and enforces a Policy independently per package.
13
7
14
8
:::Note
15
-
LavaMoat Webpack plugin does not support advanced features relying on dynamic chunk loading including Module Federation and Hot Module Reloading.
9
+
LavaMoat Webpack plugin does not support some features relying on dynamic module loading and overwriting, including Module Federation and Hot Module Reloading.
16
10
:::
17
11
18
12
## Usage
@@ -21,15 +15,13 @@ LavaMoat Webpack plugin does not support advanced features relying on dynamic ch
21
15
22
16
```shell
23
17
npm i -D @lavamoat/webpack
24
-
# or
25
-
# yarn add -D @lavamoat/webpack
26
18
```
27
19
28
20
1. Create a webpack bundle with the LavaMoat plugin enabled and the `generatePolicy` flag set to true
29
21
2. Make sure you add a `<script src="./lockdown"></script>` before all other scripts or enable the `HtmlWebpackPluginInterop` option if you're using `html-webpack-plugin`. (Note there's no `.js` there because it's the only way to prevent webpack from minifying the file thus undermining its security guarantees)
30
22
3. Tweak the policy if needed with policy-override.json
31
23
32
-
:::Note[Beta]
24
+
:::Note
33
25
Policy generation might still get confused about aliases and custom resolvers. Please report n issue if that occurs.
34
26
:::
35
27
@@ -101,17 +93,14 @@ The LavaMoat plugin takes an options object with the following properties (all o
101
93
|`readableResourceIds`| Boolean to decide whether to keep resource IDs human readable (possibly regardless of production/development mode). If `false`, they are replaced with a sequence of numbers. Keeping them readable may be useful for debugging when a policy violation error is thrown. By default, follows the Webpack config mode. |`(mode==='development')`|
102
94
|`lockdown`| Configuration for [SES lockdown][]. Setting the option replaces defaults from LavaMoat. | reasonable defaults |
103
95
|`HtmlWebpackPluginInterop`| Boolean to add a script tag to the HTML output for `./lockdown` file if `HtmlWebpackPlugin` is in use. |`false`|
104
-
|`inlineLockdown`|Array of output filenames in which to inline lockdown (instead of adding it as a file to the output directory).||
96
+
|`inlineLockdown`|A RegExp for matching files to be prepended with lockdown (instead of adding it as a file to the output directory). ||
105
97
|`runChecks`| Boolean property to indicate whether to check resulting code with wrapping for correctness. |`false`|
106
-
|`diagnosticsVerbosity`| Number property to represent diagnostics output verbosity. A larger number means more overwhelming diagnostics output. Setting a positive verbosity will enable `runChecks`. |`0`|
98
+
|`diagnosticsVerbosity`| Number property to represent diagnostics output verbosity. A larger number means more overwhelming diagnostics output. |`0`|
99
+
|`debugRuntime`| Only for local debugging use - Enables debugging tools that help detect gaps in generated policy and add missing entries to overrides |`false`|
107
100
|`policy`| The LavaMoat policy object (if not loading from file; see `policyLocation`) |`undefined`|
108
101
109
102
### Excluding modules
110
103
111
-
:::Caution
112
-
This is an experimental feature and excluding may be configured differently in the future if this approach is proven insecure.
113
-
:::
114
-
115
104
The default way to define specific behaviors for webpack is creating module rules. To ensure exclude rules are applied on the same exact files that match certain rules (the same RegExp may be matched against different things at different times) we're providing the exclude functionality as a loader you can add to the list of existing loaders or use individually.
116
105
The loader is available as `LavaMoatPlugin.exclude` from the default export of the plugin. It doesn't do anything to the code, but its presence is detected and treated as a mark on the file. Any file that's been processed by `LavaMoatPlugin.exclude` will not be wrapped in a Compartment.
117
106
@@ -166,6 +155,10 @@ Sadly, even tree shaking doesn't eliminate that module. It's left there and fail
166
155
167
156
This plugin will skip policy enforcement for such ignored modules so that they do not have to be explicitly listed in the policy file.
168
157
158
+
#### Ambient assets
159
+
160
+
Whenever webpack finds `new URL('./existing/path/to/file')` in the code it turns that file into an asset in your output folder by default. LavaMoat disables that for files requested from node_modules.
161
+
169
162
## Security
170
163
171
164
**This is an experimental software. Use at your own risk!**
0 commit comments