Modelo de ameaças do mecanismo

Visão geral

Esta página define o modelo de ameaças do mecanismo central do NextPDF. Ela lista as classes de ataque que o mecanismo considera dentro do escopo ao processar entradas influenciadas por um atacante: Hypertext Markup Language (HTML), Cascading Style Sheets (CSS), Scalable Vector Graphics (SVG), fontes, imagens e arquivos Portable Document Format (PDF) existentes. Ela declara a postura padrão de cada capacidade de recurso externo e aponta para a proteção em código que mitiga cada classe.

Limite. Um modelo de ameaças registra as ameaças consideradas e as mitigações aplicadas a elas. Ele não afirma que vulnerabilidades estejam ausentes. Uma classe não listada aqui não tem ausência comprovada; ela pode estar fora do escopo atual do modelo. Antes que recursos não implementados sejam lançados, eles passam por uma revisão formal de ameaças. Trate esta página como um registro deliberado de design, não como uma prova de segurança.

Instalação

composer require nextpdf/core:^3

As proteções descritas aqui fazem parte do pacote core. Você não precisa de nenhuma dependência extra para ativá-las. Elas já vêm ativadas por padrão.

Visão conceitual

O modelo segue o processo de modelagem de ameaças do Open Worldwide Application Security Project (OWASP) (owasp_threat_modeling#x1.x11.p6): decompor o sistema nos pontos em que uma entrada não confiável cruza um limite de confiança, enumerar as ameaças em cada limite e registrar a mitigação.

O principal limite de confiança do mecanismo é a ingestão de documentos: qualquer ponto em que conteúdo criado em outro lugar — uma folha de estilo remota, uma origem @font-face, um <image href>, uma nota fiscal Extensible Markup Language (XML) incorporada ou um PDF a inspecionar — poderia fazer o mecanismo buscar, analisar ou descomprimir dados. O princípio orientador é negar por padrão: toda capacidade de recurso externo fica desativada até que você a ative explicitamente por meio de um objeto de política. Isso aplica a linha de base de funcionalidade mínima do National Institute of Standards and Technology (NIST) SP 800-53 Rev. 5 CM-7 (nist_sp_800_53r5#x4.x182.p14) a um mecanismo de renderização: o padrão do construtor é a posição mais restritiva. Abrir uma capacidade é uma decisão explícita sua.

Superfície de API

O modelo de ameaças não é uma application programming interface (API). Os objetos de política que o expressam estão documentados nas páginas dos módulos. Os pontos de entrada relevantes para confiança são o contrato de política de recursos externos (ExternalResourcePolicyInterface, com DefaultExternalResourcePolicy como padrão de negar tudo) e as proteções de Uniform Resource Locator (URL) e XML (UrlValidator, XmlGuard). Esta página faz referência ao comportamento deles; ela não documenta novamente suas assinaturas.

Exemplo de código — Início rápido

A postura segura é o padrão. Você não precisa de código para obtê-la:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Html\DefaultExternalResourcePolicy;

// Out of the box: @font-face blocked, @import blocked, background-image
// blocked, SVG external refs blocked. A document that tries to fetch a
// remote resource gets a system-font fallback or an ignored rule — not an
// outbound request.
$policy = new DefaultExternalResourcePolicy();

Exemplo de código — Produção

Abrir uma capacidade é uma ação deliberada e restrita. Se você precisa permitir uma webfont hospedada em uma content delivery network (CDN) por Hypertext Transfer Protocol Secure (HTTPS) em produção, faça a adesão explicitamente e limite o escopo:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Html\DefaultExternalResourcePolicy;

// Explicit, scoped opt-in. The HTTPS scheme is required; size and glyph
// caps still apply; the URL still passes the SSRF guard before any fetch.
$policy = (new DefaultExternalResourcePolicy())
    ->withFontFaceAllowed(['https']);

Casos extremos e pegadinhas

Não implementado não é o mesmo que seguro por acidente. Capacidades como background-image url() de CSS não estão implementadas, então não têm superfície de ataque atual. Ainda assim, elas estão documentadas como exigindo uma barreira formal de ameaças antes de qualquer implementação futura. A ausência de código é a mitigação atual, não uma garantia permanente.
O rebinding de Domain Name System (DNS) é um alvo móvel. O UrlValidator resolve o nome de host e retorna o endereço Internet Protocol (IP) resolvido para que o chamador possa fixar a conexão (CURLOPT_RESOLVE), fechando a janela time-of-check to time-of-use (TOCTOU) entre validar e buscar. Esta é uma defesa de melhor esforço, não uma defesa absoluta. Um operador atrás de um proxy de saída permissivo ainda pode alcançar hosts internos que a biblioteca não consegue enxergar.
Bits de permissão não são controle de acesso. Um documento que “bloqueia a cópia” depende da cooperação do leitor, não de imposição. Isso é abordado no modelo de segurança. O ponto aparece aqui por ser um equívoco comum em modelos de ameaças.

Desempenho

As proteções falham rápido e limitam o trabalho: a proteção de XML rejeita uma document type declaration (DOCTYPE) antes da análise e limita o tamanho da entrada; o caminho de imagem impõe um teto de megapixels e bytes antes da descompressão; a proteção de URL rejeita por esquema e host antes que qualquer socket seja aberto. O padrão seguro resulta em uma requisição rejeitada, não em uma requisição lenta.

Notas de segurança

As classes de ataque consideradas e suas mitigações em código, com referências de Common Weakness Enumeration (CWE) e OWASP quando aplicáveis:

Classe de ameaça (CWE / OWASP)	Vetor em um mecanismo PDF	Proteção em código
Server-side request forgery (SSRF) (OWASP Top 10 2025; `owasp_top10_2025#x3.x1.p26`)	`@font-face`/`@import`/`url()` apontando para `169.254.169.254` ou um host interno; buscadores de time-stamp authority (TSA), Online Certificate Status Protocol (OCSP) e certificate revocation list (CRL)	`UrlValidator::validateExternalUrl()` bloqueia faixas privadas, reservadas, de loopback e link-local, além de endpoints de metadados de nuvem; rejeita esquemas perigosos; resolve DNS; e retorna o IP para fixação da conexão
XML external entity (XXE) (`cwe_top25_2025#x28.x2.p42`)	Entidades externas ou DOCTYPE em uma nota fiscal XML incorporada ou em um pacote Extensible Metadata Platform (XMP)	`XmlGuard::loadXml()` impõe `LIBXML_NONET`, rejeita totalmente qualquer declaração DOCTYPE, rejeita caracteres de controle proibidos pelo XML 1.0 e aplica um limite de tamanho da entrada
Bomba de descompressão	Imagem 1×1 mascarando uma carga de 100 MP; Web Open Font Format 2 (WOFF2) superdimensionado	O caminho de imagem impõe um teto de megapixels e um limite de bytes antes da descompressão; o caminho de fonte limita o tamanho do arquivo e a contagem de glifos
Path traversal	`file:///etc/passwd` via uma fonte ou SVG `src`	Recursos externos negam tudo por padrão; caminhos de arquivos locais resolvidos via `realpath()` contra uma allowlist de diretórios quando explicitamente habilitado
Injeção de conteúdo	String forjada que escapa de um operador PDF; `data:`/`javascript:` href	Escape de strings PDF na emissão; allowlist de esquemas e sanitização de href em anotações

Os padrões compõem uma postura de negar tudo para recursos externos: fonte, @import, background-image e referências externas de SVG permanecem desativadas até que você faça a adesão por esquema, como descrito na matriz de cobertura de propriedades de segurança mantida junto ao código.

Esta página documenta ameaças consideradas. Ela não é um relatório de teste de penetração e não afirma que as mitigações listadas estejam completas nem que nenhuma outra classe de fraqueza se aplique.

Conformidade

Este não é um perfil de conformidade. O modelo de ameaças é informado pelo processo de modelagem de ameaças da OWASP e pela taxonomia de fraquezas CWE Top 25 (cwe_top25_2025#x28.x2.p42); ele não afirma conformidade com nenhum esquema de certificação de segurança. A avaliação independente pertence a uma auditoria, não a este documento.