pub enum SafeMode {
Unsafe = 0,
Safe = 1,
Server = 10,
Secure = 20,
}Expand description
Describes the safe mode under which a document is parsed and rendered.
Safe modes provide a security model that controls how much a document is
allowed to reach outside of itself. They mirror the safe modes defined by
Ruby Asciidoctor, and the discriminant values are chosen so that the
modes compare in order of increasing safety (Unsafe < Safe < Server <
Secure). Features that could expose the host environment (for example,
embedding the contents of a file directly in the output) are only enabled
when the safe mode is below a threshold.
The default safe mode is SafeMode::Secure, matching the most
conservative setting. A client may relax it via
Parser::with_safe_mode.
§This crate performs no path-jail enforcement
Unlike Ruby Asciidoctor, this crate performs no filesystem I/O of its
own. Reading include:: targets, images, and SVGs is delegated to the
client via IncludeFileHandler,
ImageFileHandler, and
SvgFileHandler. As a consequence, the
path-traversal jail that Ruby Asciidoctor applies through
PathResolver#system_path – rejecting or clamping ../, absolute paths,
file:// URIs, and symlinks that escape a jail root – is deliberately not
ported (see PathResolver). Below
Secure, the raw include/image/SVG target is handed to the
client handler verbatim, with no traversal check and without communicating
any jail boundary.
Enforcing a jail is therefore the client handler’s responsibility. A
handler that resolves untrusted targets against the filesystem must itself
reject ../, absolute paths, and file:// targets and resolve symlinks
against its own jail root; the safe mode alone will not do this for it.
Variants§
Unsafe = 0
A safe mode level that disables any of the security features enforced by Asciidoctor (Ruby or otherwise). This mode is intended for use when the document is entirely trusted.
Safe = 1
In Ruby Asciidoctor, this level parallels Unsafe
except that it prevents access to files which reside outside of the
parent directory of the source file.
This crate does not enforce that jail. Because path resolution is
delegated to the client handlers (see the type-level
docs), Safe
currently imposes no restriction beyond Unsafe: the
include/image/SVG handlers are consulted and their contents embedded
exactly as under Unsafe, and no ..//absolute/file:// traversal
check is applied. Keeping untrusted targets inside a directory is the
handler’s responsibility.
Server = 10
A safe mode level intended for server deployments (hence the name).
In this crate, Server masks host-revealing intrinsic attributes so
they cannot leak into rendered output: docdir reads as empty,
docfile is relativized against docdir, and user-home reads as .
rather than the real home directory.
Server does not by itself disable include or asset embedding.
Unlike what its name might suggest, at Server (and every level below
Secure) the include/image/SVG handlers are consulted
and file contents are embedded: include:: directives pull in file
contents, data-uri images are base64-embedded, and inline/interactive
SVGs are embedded. Disabling that embedding – and applying any path jail
– happens only at Secure (for embedding) or in the
client handler (for the jail). A server-side integrator that must not
embed arbitrary file contents should use Secure, not
Server.
Secure = 20
A safe mode level that disables the embedding of file contents into the output.
At Secure (and above), include:: directives are converted to links
to their targets rather than embedding file contents, data-uri image
embedding is disabled, inline and interactive SVGs render as ordinary
<img> elements, and docinfo files are ignored. This is the level at
which the include/image/SVG handlers stop being consulted for embedding.
This mode allows the AsciiDoc document to be processed in a shared,
server-side environment, such as a wiki, where the document should not
be able to embed the contents of arbitrary files. Note that Secure
still enforces no path-traversal jail of its own (there is nothing left
for a jail to guard, since embedding is off); a client that resolves
targets against the filesystem at a lower safe mode must jail them
itself (see the type-level
docs).
This is the default safe mode.