Resource loading and security¶
A document can reference other files: stylesheets (<link rel="stylesheet">, @import), images (<img>,
<object>, <embed>, SVG <image>, CSS url()), web fonts (@font-face) and attachments
(<link rel="attachment">). kolinsky loads all of them, and the input itself when it is a URL, through one
fetcher, under an access policy that you set per call. When the documents you render are not your own,
the policy decides what they can read.
Read directly, outside the fetcher and the policy, are only what you name yourself: an input given as a file path, the fonts you add to the engine, the system fonts and the attachments of the PDF options.
What the default fetcher loads¶
| URLs | Loaded |
|---|---|
data: |
always |
file: |
every file the process can read, or only the files inside root when it is set |
http:, https: |
never by default; when the network is allowed, all or the URLs that match a pattern |
| any other scheme | never (resource.unsupported); a custom fetcher can serve it |
Within one call each URL is loaded at most once, and the answer (a failure included) is used for every reference to it. Nothing is cached between calls.
A resource that cannot be loaded is not an error: it is skipped and reported as a resource.* diagnostic
(resource.not-found, resource.denied, resource.timeout, resource.too-large, resource.unsupported,
resource.failed, resource.invalid) at the element or declaration that references it. Only the input itself
and the user stylesheets you pass fail the call when they cannot be loaded. Use
strict mode to fail on missing resources.
Base URLs¶
Relative references resolve against the document's base URL: the file's URL for a file input, the final URL
for a URL input, and for HTML text the base URL you pass with it. A <base href> element replaces it. HTML
text without a base URL cannot resolve relative references; they give resource.unresolved. On the command line,
--base-url sets the base URL of every input (standard input defaults to the working directory).
Network access¶
The network is off by default: every http: and https: URL is denied before any connection is made. Allow it
for all URLs (--allow-net, allow_network=True, NetworkAccess::AllowAll), or only for the URLs that match
one of a list of patterns (--allow-net=PATTERN, repeatable).
A pattern is scheme://host[:port][/path]:
- the scheme is
httporhttpsand must be the URL's scheme; - the host is compared ignoring case;
*.example.commatches every host belowexample.com(cdn.example.com,a.b.example.com) but notexample.comitself; - without a port the URL must use the scheme's default port; with one it must use that port;
- a path is a prefix of the URL's path:
/assets/matches everything below it,/imgmatches/img,/img/a.pngand/images. The query is ignored.
| Pattern | Matches | Does not match |
|---|---|---|
https://example.com |
https://example.com/a.css |
http://example.com/a.css, https://cdn.example.com/a.css |
https://*.example.com |
https://cdn.example.com/x.png |
https://example.com/x.png |
https://example.com:8443/assets/ |
https://example.com:8443/assets/logo.svg |
https://example.com/assets/logo.svg |
A * anywhere else, user information, an empty host and other schemes are invalid patterns and are rejected
before anything is loaded. Redirects are followed (up to 10) and each target is checked against the policy
again.
The root directory¶
With root (--root DIR) set, a file: URL is loaded only when the file, with symbolic links and ..
resolved, is inside that directory. A file outside the root is denied, also when it does not exist, so a
document cannot find out which files exist outside it. Without root every file the process can read is
allowed. The root does not limit the input file, user stylesheets given as paths, fonts or the attachments of
the PDF options.
Limits¶
timeout (--timeout SECONDS, 30 seconds by default) bounds each fetch, connection and redirects included.
max_resource_size (--max-resource-size, 64 MiB by default, with the suffixes K, M and G on the command
line) bounds the size of each resource after decoding. A resource over a limit is abandoned
(resource.timeout, resource.too-large).
The options together, on the command line:
kolinsky render hello.html -o hello.pdf --allow-net=https://cdn.example.com/assets/ --allow-net=https://*.example.org --root . --timeout 10 --max-resource-size 16M
In Rust, the policy is RenderOptions::access:
use kolinsky::{Engine, Input, NetworkAccess, PdfOptions, RenderOptions};
use std::time::Duration;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut options = RenderOptions::default();
// Only these hosts and paths; every other http: and https: URL is denied
options.access.network = NetworkAccess::AllowList(vec!["https://cdn.example.com/assets/".parse()?, "https://*.example.org".parse()?]);
// file: URLs only inside the current folder
options.access.root = Some(std::env::current_dir()?);
options.access.timeout = Duration::from_secs(10);
options.access.max_resource_size = 16 << 20;
let rendered = Engine::new().render(Input::Path("hello.html".into()), &options, &PdfOptions::default())?;
std::fs::write("hello.pdf", rendered.output)?;
Ok(())
}
In Python, the same fields are options:
from pathlib import Path
import kolinsky
options = kolinsky.Options(
allow_network=("https://cdn.example.com/assets/", "https://*.example.org"),
root=".",
timeout=10.0,
max_resource_size=16 * 1024 * 1024,
)
result = kolinsky.render(Path("hello.html"), options=options)
Path("hello.pdf").write_bytes(result.pdf)
Custom fetchers¶
An engine can be built with a fetcher of your own. It sees every request with its URL, its kind (document,
stylesheet, image, font, attachment) and the call's access policy, and it can answer from anywhere: a
database, an archive, the application's own assets under a scheme like app://. For the URLs it does not
handle it calls the default fetcher, which applies the policy as usual.
The engine trusts the answers of a custom fetcher: what it serves itself is not checked against the access
policy, so it is responsible for its own rules. A fetcher can also remap a URL and pass the new one to the
default fetcher (request.with_url(&url) in Rust, request.default(url) in Python); the remapped URL is then
checked against the policy. The URL of the resource it returns is the base for the references inside the
resource.
use kolinsky::{DefaultFetcher, Engine, FetchError, FetchErrorKind, FetchRequest, Fetcher, Input, PdfOptions, RenderOptions, Resource};
const LOGO: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><circle cx="5" cy="5" r="4" fill="#c25129"/></svg>"##;
/// Serves `app:` URLs from memory and hands every other URL to the default fetcher, which applies the access policy.
struct AppFetcher {
inner: DefaultFetcher,
}
impl Fetcher for AppFetcher {
fn fetch(&self, request: &FetchRequest<'_>) -> Result<Resource, FetchError> {
if request.url.scheme() == "app" {
return match request.url.as_str() {
"app://logo.svg" => Ok(Resource { bytes: LOGO.as_bytes().to_vec(), content_type: Some("image/svg+xml".into()), url: request.url.clone() }),
other => Err(FetchError::new(FetchErrorKind::NotFound, format!("no asset {other}"))),
};
}
self.inner.fetch(request)
}
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let engine = Engine::builder().fetcher(AppFetcher { inner: DefaultFetcher::new() }).build();
let rendered = engine.render(Input::Path("app.html".into()), &RenderOptions::default(), &PdfOptions::default())?;
assert!(rendered.diagnostics.is_empty(), "{:?}", rendered.diagnostics);
std::fs::write("app.pdf", rendered.output)?;
Ok(())
}
In Python, a fetcher is a callable that takes a kolinsky.Request and returns a kolinsky.Resource. It fails by
raising kolinsky.KolinskyFetchError with a kind (not-found, denied, timeout, too-large,
unsupported, failed); any other exception counts as failed.
from pathlib import Path
import kolinsky
LOGO = b'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><circle cx="5" cy="5" r="4" fill="#c25129"/></svg>'
def fetcher(request: kolinsky.Request) -> kolinsky.Resource:
# app: URLs from memory, everything else through the default fetcher and the access policy
if request.url == "app://logo.svg":
return kolinsky.Resource(LOGO, content_type="image/svg+xml")
if request.url.startswith("app:"):
raise kolinsky.KolinskyFetchError(f"no asset {request.url}", kind="not-found")
return request.default()
engine = kolinsky.Engine(fetcher=fetcher)
result = engine.render(Path("app.html"))
Path("app.pdf").write_bytes(result.pdf)
Untrusted documents¶
For documents you do not control, keep the network off or allow only the hosts you need, set root to the
directory of the document's assets, and keep the limits low enough for your service. Rendering is CPU-bound
and runs in your process; run untrusted renders where a long or large job cannot affect other work, and use
strict mode when a missing resource should fail the job.