Proteger aplicativos web do Tomcat

tomcat converte um WAR numa base Tomcat autossuficiente. Ele usa os componentes do Tomcat embutidos no empacotador e não toca na instalação do Tomcat da sua máquina.

1. Pela interface gráfica

1. Na página do tipo de aplicativo, escolha Tomcat WAR.

   

2. Selecione o WAR de entrada, a versão do Java a incluir e as plataformas-alvo, e escolha entre modo simples ou avançado.

   

3. No modo avançado, escolha Tomcat 9 ou 10.1, ou deixe a detecção automática, e ajuste conforme necessário o caminho de contexto, as opções da JVM e as regras de exclusão. O modo simples determina a versão do Tomcat a partir da verificação de compatibilidade. O significado de cada opção está em Configurações do modo avançado do Protector4J.

   

4. Escolha a pasta de saída, confira o resumo e clique em Executar proteção.

   

2. Exemplos de linha de comando

Informar o caminho de contexto:

p4j tomcat app.war dist --context /app

Verificação de compatibilidade e aplicação automática das recomendações:

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

As duas opções não podem ser usadas juntas. A diferença é esta:

Para tomcat, --compat-apply pode acrescentar regras de exclusão a partir da verificação e ajustar a versão do Tomcat, a camada ZIP e o sufixo do arquivo. Nesses três últimos casos, prevalece o valor informado explicitamente na linha de comando. As exclusões recomendadas são combinadas por padrão com os seus próprios padrões --exclude; acrescente --no-compat-excludes se não quiser isso. O scanner faz apenas análise heurística estática, de modo que os problemas que exigem mudanças no código não são resolvidos por --compat-apply, e o aplicativo empacotado continua precisando de testes de regressão na plataforma-alvo.

Os demais comandos, todas as opções, as variáveis de ambiente e os exemplos de automação estão na Referência da linha de comando.

--tomcat-version vale auto por padrão. Ajuste para 9 ou 10.1 quando quiser fixá-la:

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

3. Estrutura da 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 não se gera um WAR físico. O web.xml, os recursos estáticos, as classes sem proteção, os esboços de metadados e as implementações protegidas ficam todos em protected/<contexto>.p4jx, apresentado ao Tomcat pelo WebResourceSet do P4JX.

4. Iniciar e parar

Em primeiro plano:

./run.sh

Em segundo plano, ao estilo do Tomcat:

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

No Windows, use os .bat correspondentes. Os registros são gravados na pasta logs/ da saída.

Para alvos Windows também é possível gerar um iniciador nativo que sobe o Tomcat embutido em primeiro plano — veja Criar um iniciador EXE do Windows.

Opções de inicialização JVM

Ao empacotar, digite uma opção por linha em Opções de inicialização JVM na interface gráfica, ou informe-as na linha de comando:

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

Para alterá-las num pacote já implantado:

• macOS e Linux: edite bin/catalina.sh e acrescente JVM_OPTS+=("-Xms1g" "-Xmx2g") depois da linha JVM_OPTS=(...) dentro de run_java(). Vale tanto para a execução em primeiro plano quanto para a inicialização por startup.sh.
• Windows, primeiro plano: edite bin\catalina.bat e acrescente set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g" depois da linha set "JVM_OPTS=..." existente.
• Windows, segundo plano: acrescente set "APP_JAVA_OPTS=-Xms1g -Xmx2g" em bin\startup.bat antes da chamada a catalina.bat. Se precisar de um conjunto permanente de opções para os dois casos, é mais simples gerar o pacote de novo pela interface ou pela linha de comando.

Também é possível colocar APP_JAVA_OPTS antes do comando para valer só naquela execução. Os exemplos completos para CMD, PowerShell e scripts estão em Opções de inicialização JVM.

5. Escolher a versão do Tomcat

A detecção automática identifica o espaço de nomes primeiro pelas classes do aplicativo e pelos descritores de implantação; os nomes dos JAR servem apenas como indício secundário. Se javax e jakarta convivem, a ferramenta se recusa a adivinhar.

6. JSP

Quando um WAR contém arquivos JSP, eles são pré-compilados em classes de servlet e mapeamentos de URL durante a codificação. Compilar JSP em tempo de execução definiria novas classes a partir da pasta de trabalho do Tomcat, fora do limite que o tempo de execução protegido permite para definição de classes.

É possível controlar isso explicitamente:

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

Em produção, mantenha a pré-compilação padrão. Desligá-la pode impedir o carregamento das páginas de um aplicativo baseado em JSP.

7. Alcance da proteção e regras de exclusão

Por padrão, as classes de aplicativo sob WEB-INF/classes são protegidas, e WEB-INF/lib fica de fora. As classes voltadas à web podem ser excluídas:

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

Exclua primeiro servlets, filtros e ouvintes, e também DTOs, classes de configuração, entidades, classes-ponte JNI e tudo o que o contêiner precise ampliar. A verificação de compatibilidade oferece recomendações conservadoras.

8. Acrescentar outro aplicativo ao mesmo pacote Tomcat

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

Restrições:

• o caminho de contexto não pode coincidir com o de um aplicativo já existente;
• o aplicativo existente e o novo precisam usar a mesma versão principal do Tomcat, a mesma versão do Java e a mesma plataforma-alvo;
• sem --append-app, a ferramenta se recusa a gravar num pacote Tomcat existente;
• na interface gráfica, marque Adicionar o aplicativo a uma pasta Tomcat existente e escolha a pasta já criada.

9. Observação sobre o Java 8

Nos alvos Java 8, a camada ZIP é ativada automaticamente para que o WebResourceSet do Tomcat consiga abrir o arquivo protegido.