diff --git a/runtime/fundamentals/security.md b/runtime/fundamentals/security.md index b0b2b4528..ff0785268 100644 --- a/runtime/fundamentals/security.md +++ b/runtime/fundamentals/security.md @@ -96,10 +96,11 @@ By default, Deno will not generate a stack trace for permission requests as it comes with a hit to performance. Users can enable stack traces with the `DENO_TRACE_PERMISSIONS` environment variable to `1`. -Deno can also generate an audit log of all accessed permissions; this can be -achieved using the `DENO_AUDIT_PERMISSIONS` environment variable to a path. This -works regardless if permissions are allowed or not. The output is in JSONL -format, where each line is an object with the following keys: +Deno can also generate an audit log of all accessed permissions, regardless of +whether the access was allowed or denied. + +Set `DENO_AUDIT_PERMISSIONS` to a **file path** to write JSONL — each line is an +object with the following keys: - `v`: the version of the format - `datetime`: when the permission was accessed, in RFC 3339 format @@ -112,7 +113,24 @@ A schema for this can be found in In addition, this env var can be combined with the above-mentioned `DENO_TRACE_PERMISSIONS`, which then adds a new `stack` field to the entries -which is an array contain all the stack trace frames. +which is an array containing all the stack trace frames. + +You can also set `DENO_AUDIT_PERMISSIONS=otel` to emit each access as an +OpenTelemetry **log record** instead of writing to a file. The records are sent +to whichever exporter you have configured via +[`OTEL_DENO`](/runtime/fundamentals/open_telemetry/) and carry these attributes: + +- `deno.permission.type` +- `deno.permission.value` +- `deno.permission.stack` (if `DENO_TRACE_PERMISSIONS` is also set) + +This is the recommended setup if you already collect OpenTelemetry data — the +permission audit lands next to your traces and metrics so you can correlate it +with request handling. + +```sh +OTEL_DENO=true DENO_AUDIT_PERMISSIONS=otel deno run -A main.ts +``` ### Configuration file diff --git a/runtime/reference/env_variables.md b/runtime/reference/env_variables.md index 8769046bc..69a8a9387 100644 --- a/runtime/reference/env_variables.md +++ b/runtime/reference/env_variables.md @@ -138,25 +138,26 @@ examples. The Deno runtime has these special environment variables. -| name | description | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| DENO_AUTH_TOKENS | A semi-colon separated list of bearer tokens and hostnames to use when fetching remote modules from private repositories
(e.g. `abcde12345@deno.land;54321edcba@github.com`) | -| DENO_TLS_CA_STORE | Comma-separated list of order dependent certificate stores.
Possible values: `system`, `mozilla`. Defaults to `mozilla`. | -| DENO_CERT | Load certificate authority from PEM encoded file | -| DENO_COVERAGE_DIR | Set the directory for collecting coverage profile data. This option only works for [`deno test` subcommand](/runtime/reference/cli/test/). | -| DENO_DIR | Set the cache directory | -| DENO_INSTALL_ROOT | Set deno install's output directory (defaults to `$HOME/.deno/bin`) | -| DENO_REPL_HISTORY | Set REPL history file path History file is disabled when the value is empty
(defaults to `$DENO_DIR/deno_history.txt`) | -| DENO_NO_PACKAGE_JSON | Disables auto-resolution of `package.json` | -| DENO_NO_PROMPT | Set to disable permission prompts on access
(alternative to passing `--no-prompt` on invocation) | -| DENO_NO_UPDATE_CHECK | Set to disable checking if a newer Deno version is available | -| DENO_V8_FLAGS | Set V8 command line options | -| DENO_JOBS | Number of parallel workers used for the `--parallel` flag with the test subcommand.
Defaults to number of available CPUs. | -| DENO_KV_ACCESS_TOKEN | Personal access token used when connecting to Deno KV databases (for example via [`Deno.openKv`](/api/deno/~/Deno.openKv) or `@deno/kv` with a KV Connect URL). | -| DENO_WEBGPU_TRACE | Path to a directory to output a [WGPU trace](https://github.com/gfx-rs/wgpu/pull/619) to when using the WebGPU API | -| DENO_WEBGPU_BACKEND | Select the backend WebGPU will use, or a comma separated list of backends in order of preference. Possible values are `vulkan`, `dx12`, `metal`, or `opengl` | -| HTTP_PROXY | Proxy address for HTTP requests (module downloads, fetch) | -| HTTPS_PROXY | Proxy address for HTTPS requests (module downloads, fetch) | -| NPM_CONFIG_REGISTRY | URL to use for the npm registry. | -| NO_COLOR | Set to disable color | -| NO_PROXY | Comma-separated list of hosts which do not use a proxy (module downloads, fetch) | +| name | description | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| DENO_AUTH_TOKENS | A semi-colon separated list of bearer tokens and hostnames to use when fetching remote modules from private repositories
(e.g. `abcde12345@deno.land;54321edcba@github.com`) | +| DENO_TLS_CA_STORE | Comma-separated list of order dependent certificate stores.
Possible values: `system`, `mozilla`. Defaults to `mozilla`. | +| DENO_CERT | Load certificate authority from PEM encoded file | +| DENO_COVERAGE_DIR | Set the directory for collecting coverage profile data. This option only works for [`deno test` subcommand](/runtime/reference/cli/test/). | +| DENO_DIR | Set the cache directory | +| DENO_INSTALL_ROOT | Set deno install's output directory (defaults to `$HOME/.deno/bin`) | +| DENO_REPL_HISTORY | Set REPL history file path History file is disabled when the value is empty
(defaults to `$DENO_DIR/deno_history.txt`) | +| DENO_NO_PACKAGE_JSON | Disables auto-resolution of `package.json` | +| DENO_NO_PROMPT | Set to disable permission prompts on access
(alternative to passing `--no-prompt` on invocation) | +| DENO_NO_UPDATE_CHECK | Set to disable checking if a newer Deno version is available | +| DENO_V8_FLAGS | Set V8 command line options | +| DENO_JOBS | Number of parallel workers used for the `--parallel` flag with the test subcommand.
Defaults to number of available CPUs. | +| DENO_KV_ACCESS_TOKEN | Personal access token used when connecting to Deno KV databases (for example via [`Deno.openKv`](/api/deno/~/Deno.openKv) or `@deno/kv` with a KV Connect URL). | +| DENO_AUDIT_PERMISSIONS | Audit every permission access. Set to a file path to write JSONL, or to the literal value `otel` to emit OpenTelemetry log records via the configured OTel exporter. See [permissions audit](/runtime/fundamentals/security/#permission-flags) for the field set. | +| DENO_WEBGPU_TRACE | Path to a directory to output a [WGPU trace](https://github.com/gfx-rs/wgpu/pull/619) to when using the WebGPU API | +| DENO_WEBGPU_BACKEND | Select the backend WebGPU will use, or a comma separated list of backends in order of preference. Possible values are `vulkan`, `dx12`, `metal`, or `opengl` | +| HTTP_PROXY | Proxy address for HTTP requests (module downloads, fetch) | +| HTTPS_PROXY | Proxy address for HTTPS requests (module downloads, fetch) | +| NPM_CONFIG_REGISTRY | URL to use for the npm registry. | +| NO_COLOR | Set to disable color | +| NO_PROXY | Comma-separated list of hosts which do not use a proxy (module downloads, fetch) |