Proteção da aplicação Web do Tomcat

tomcat converte um WAR em uma base Tomcat autônoma. Durante a execução, são utilizados os componentes Tomcat embutidos no encoder, sem necessidade de acessar a instalação do Tomcat local do usuário.

1. Operações via GUI

Selecione Tomcat WAR na página de tipo de aplicação.
Escolha a entrada WAR, Versão Java incluída no pacote e a plataforma de destino, e selecione o modo simples ou o modo avançado.
No modo avançado, escolha Tomcat 9/10.1 ou mantenha a detecção automática, e defina o Context Path, parâmetros JVM e regras de exclusão conforme necessário; o modo simples sugere a versão do Tomcat por meio de uma varredura de compatibilidade. As descrições de cada opção estão em Configurações do modo avançado do Protector4J.
Escolha o diretório de saída, revise o resumo dos parâmetros e, em seguida, clique em Run protection.

2. Exemplo de CLI

Caminho de contexto especificado:

p4j tomcat app.war dist --context /app

Varredura de compatibilidade e sugestões automáticas de aplicação:

p4j tomcat app.war --compat-scan
p4j tomcat app.war dist --compat-apply --context /app

Essas duas opções não podem ser usadas simultaneamente; a diferença entre elas é:

Opção	Comportamento	Quando usar
`--compat-scan`	Apenas escaneia o WAR de entrada, exibe riscos e sugestões de configuração e depois encerra; não realiza codificação nem gera `dist`, portanto não é necessário um diretório de saída	Use-o primeiro para visualizar relatórios após proteger uma aplicação pela primeira vez, atualizar dependências relacionadas ao Tomcat, ajustar o escopo de proteção ou a configuração JSP, bem como ao resolver problemas de compatibilidade
`--compat-apply`	Após a varredura, as sugestões conservadoras são automaticamente combinadas, e em seguida a codificação continua para gerar a saída; portanto, é necessário especificar o diretório de saída.	Quando os resultados da varredura são lidos e as sugestões automáticas aceitas, elas são utilizadas para concluir a compactação; também pode ser usado em construções repetidas com regras já verificadas ou em fluxos CI.

Para tomcat e --compat-apply, é possível adicionar classes de exclusão com base nos resultados da varredura, além de ajustar opções como a versão do Tomcat, o ZIP overlay e o sufixo do arquivo compactado. Para essas três últimas opções, os valores especificados explicitamente na linha de comando têm prioridade; as classes de exclusão sugeridas são, por padrão, combinadas com as especificadas em --exclude. Se não desejar que classes de exclusão sejam adicionadas automaticamente, é possível passar --no-compat-excludes simultaneamente. O scanner realiza apenas análise heurística estática; problemas que exigem modificação no código não serão corrigidos automaticamente por --compat-apply, e testes de regressão ainda são necessários na plataforma-alvo após a geração.

Para outros comandos CLI, todas as opções, variáveis de ambiente e exemplos de automação, consulte Referência de parâmetros CLI.

--tomcat-version tem como valor padrão auto. Se necessário, é possível especificar explicitamente 9 ou 10.1.

p4j tomcat app.war dist --context /app --tomcat-version 10.1

3. Estrutura de saída

dist/
├── bin/
│   ├── catalina.sh
│   ├── startup.sh
│   ├── shutdown.sh
│   └── *.bat
├── conf/p4jx/
│   ├── contexts.list
│   ├── protected-classes.list
│   └── allowed-prefixes.list
├── protected/
│   └── app.p4jx
├── lib/
│   ├── p4jx-tomcat-runtime.jar
│   └── tomcat-runtime-deps.jar
├── vlxjre/
├── run.sh
└── run.bat

Por padrão, nenhum WAR físico é gerado. web.xml, recursos estáticos, classes públicas, dados de metadados fictícios e implementações de proteção estão localizados em protected/<context>.p4jx, sendo exibidos ao Tomcat por meio do P4JX WebResourceSet.

4. Início e parada

Execução na frente do usuário:

./run.sh

Início no modo Tomcat, na parte de trás:

./bin/startup.sh
./bin/shutdown.sh

No Windows, use o arquivo correspondente .bat. Os logs são gravados em logs/, no diretório de saída.

Parâmetros de inicialização do JVM

Durante a compactação, é possível preencher um parâmetro por linha em JVM startup options na GUI, ou usar a CLI:

p4j tomcat app.war dist \
  --context /app \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

Modificação direta após a implantação:

macOS/Linux: edite bin/catalina.sh e adicione JVM_OPTS+=("-Xms1g" "-Xmx2g") após JVM_OPTS=(...) em run_java(); isso terá efeito tanto no início na frente do usuário quanto em startup.sh, na parte de trás.
Windows, na frente do usuário: edite bin\catalina.bat e adicione set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g" após o set "JVM_OPTS=..." original.
Plano de fundo do Windows: adicione set "APP_JAVA_OPTS=-Xms1g -Xmx2g" antes de chamar catalina.bat em bin\startup.bat. Se for necessário compartilhar o mesmo conjunto de parâmetros persistentes entre os planos de fundo e de frente, recomenda-se gerá-los novamente por meio de GUI/CLI.

Para inicialização temporária, também é possível definir APP_JAVA_OPTS antes do comando. Exemplos completos em CMD, PowerShell e scripts estão disponíveis em Configuração de parâmetros de inicialização do JVM.

5. Escolha da versão do Tomcat

Espaço de nomes da API WAR	Tomcat	Requisitos do Java
`javax.servlet.*`	Tomcat 9	Java 8/11/17/21/25
`jakarta.servlet.*`	Tomcat 10.1	Java 11/17/21/25

A detecção automática prioriza a identificação do espaço de nomes da API a partir de classes de aplicação e descritores de deploy, usando os nomes dos arquivos JAR apenas como evidência auxiliar. Quando javax e jakarta são usados simultaneamente, a ferramenta recusa fazer suposições automáticas.

6. JSP

Quando um WAR contém JSP, ele é automaticamente pré-compilado em classes servlet e mapeamentos de URL durante a fase de codificação. Isso ocorre porque a compilação dinâmica de JSP em tempo de execução define novas classes no diretório de trabalho do Tomcat, o que não está alinhado com o escopo de proteção das definições de classes em tempo de execução.

É possível controlar isso explicitamente:

--precompile-jsp
--no-precompile-jsp

Recomenda-se manter a compilação automática padrão no ambiente de produção. Ao desativá-la, aplicações que contêm JSP podem falhar ao acessar as páginas.

7. Escopo de proteção e regras de exclusão

A proteção padrão se aplica às classes de aplicação WEB-INF/classes, enquanto WEB-INF/lib depende da proteção padrão e não é protegida. É possível excluir classes voltadas para o público da web:

p4j tomcat app.war dist \
  --context /app \
  --exclude 'com.example.web.**,com.example.dto.**'

Deve-se priorizar a exclusão de servlets/filtros/listeners, DTOs, configurações, entidades, classes de ponte JNI e classes que precisam de aprimoramentos pelo container. A verificação de compatibilidade fornecerá recomendações cautelosas.

8. Adicionar uma aplicação ao mesmo pacote do Tomcat

p4j tomcat second.war dist \
  --append-app \
  --context /second

Restrições:

O path do contexto não pode ser repetido por outra aplicação existente;
As aplicações antigas e novas devem usar a mesma versão principal do Tomcat, versão do Java e plataforma de destino;
Quando --append-app não é fornecido, a ferramenta se recusa a gravar em um pacote Tomcat existente;
Marque “Append application to an existing Tomcat folder” na interface gráfica e selecione diretamente o diretório existente.

9. Observações para Java 8

O destino Java 8 ativará automaticamente o ZIP overlay, permitindo que o Tomcat WebResourceSet abra arquivos compactados protegidos.