Instalação direta

O PEART é distribuído como dois binários Go estáticos, peart (a superfície interna que o pentester usa) e peart-portal (a superfície que o cliente usa), mais um sidecar de renderização em Python que transforma o HTML do relatório em PDF. Esta página instala os binários direto num host Linux. O caminho por container fica em página própria; a instalação direta é a escolha certa para um host endurecido ou auditado, onde ter menos partes móveis já é uma propriedade de segurança.

Não existe credencial padrão. No primeiro acesso o PEART exige que você crie o administrador, incluindo a inscrição do segundo fator.

Método 1, binários assinados de release (recomendado)

Cada release marcado publica binários cross-compilados para linux/amd64 e linux/arm64, um manifesto checksums.txt, um sbom.json em CycloneDX e assinaturas Sigstore para os dois. Baixe os binários da sua arquitetura junto com checksums.txt, checksums.txt.sig e checksums.txt.pem na página de releases.

Verifique a assinatura do manifesto antes de confiar nele. O release é assinado sem chave (keyless) com o cosign, então não há chave pública a buscar; a identidade é o próprio fluxo de release:

cosign verify-blob \
  --certificate-identity-regexp 'https://github.com/mentesan/peart/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --signature checksums.txt.sig --certificate checksums.txt.pem \
  checksums.txt

Depois confira os binários contra o manifesto verificado e instale:

sha256sum --check --ignore-missing checksums.txt
sudo install -m 0755 peart-linux-amd64        /usr/local/bin/peart
sudo install -m 0755 peart-portal-linux-amd64 /usr/local/bin/peart-portal
peart version

A página Verificar a instalação mostra como verificar a assinatura do SBOM e a imagem de container da mesma forma.

Método 2, go install

Com um toolchain Go na versão que o go.mod do projeto declara, instale os dois comandos a partir do fonte sem clonar:

go install github.com/mentesan/peart/cmd/peart@vX.Y.Z
go install github.com/mentesan/peart/cmd/peart-portal@vX.Y.Z

Fixe a tag de versão exata em vez de @latest, para você saber o que compilou. Esse caminho compila na sua máquina e não carrega as assinaturas do release, então prefira o Método 1 quando quiser os artefatos assinados e atestados.

Método 3, a partir do fonte

Para quem contribui, ou para compilar dentro de um ambiente isolado a partir de um checkout auditado:

git clone https://github.com/mentesan/peart.git
cd peart
make build          # produz bin/peart e bin/peart-portal

A compilação é cross-compilação pura sem CGO (ADR 0004), então compilar para outra arquitetura Linux exige apenas GOOS/GOARCH, não uma segunda máquina nem emulação.

Os usuários e grupos (bare metal)

Nada daqui para baixo funciona antes que eles existam. Três contas de serviço rodam os três processos, e todo install -d, chown e sudo -u desta página e da próxima chama uma delas pelo nome. Crie as contas uma vez, aqui, antes de qualquer coisa usá-las:

sudo groupadd --system peart
sudo groupadd --system peart-portal
sudo groupadd --system peart-render
sudo groupadd --system peart-work

sudo useradd --system --gid peart        --no-create-home --shell /usr/sbin/nologin peart
sudo useradd --system --gid peart-portal --no-create-home --shell /usr/sbin/nologin peart-portal
sudo useradd --system --gid peart-render --home-dir /opt/peart/render --shell /usr/sbin/nologin peart-render

Cada conta ganha um grupo de mesmo nome, e o --gid diz isso em vez de confiar na distribuição para criá-lo: se o useradd faz isso sozinho depende do USERGROUPS_ENAB, e o bloco de permissões da página seguinte trata peart e peart-portal como grupos, não só como usuários. Nenhuma das três tem shell de login nem home que não precise; o home do peart-render é o diretório do virtualenv de onde o sidecar roda, criado poucas linhas abaixo.

O peart-work é o quarto grupo e o diferente dos outros: ele não pertence a conta nenhuma. É o grupo que o peart e o peart-render compartilham sobre o diretório de job, onde um prepara o relatório e o outro renderiza, e as units entregues põem os dois processos nele com SupplementaryGroups=peart-work, então não há usermod para lembrar aqui. A página Primeira execução e configuração é a dona do diretório em si.

Se você já tem uma instalação do PEART, essas contas existem e esta seção não é para você. Deixe-as exatamente como estão, com as opções que tiverem.

Instalar o sidecar de renderização (bare metal)

Os três métodos acima instalam os binários Go e nada mais. A geração de PDF passa por um sidecar em Python, e numa instalação bare metal ele é por sua conta: o peart-render.service espera encontrá-lo em /opt/peart/render, rodando de um virtualenv ali. Sem ele a aplicação sobe e funciona, e toda geração de relatório falha.

O caminho por container não precisa de nada disso: a imagem já traz o sidecar e suas dependências.

O diretório de job de onde o sidecar trabalha não é criado aqui. Ele é compartilhado com o processo peart e faz parte da árvore de dados, que a página Primeira execução e configuração governa num lugar só, grupo e modos incluídos.

sudo install -d -o peart-render -g peart-render /opt/peart/render
sudo cp render/app.py render/requirements.txt /opt/peart/render/

sudo -u peart-render python3 -m venv /opt/peart/render/.venv
sudo -u peart-render /opt/peart/render/.venv/bin/pip install \
    --require-hashes -r /opt/peart/render/requirements.txt

O --require-hashes não é enfeite. Toda distribuição em requirements.txt está fixada por versão e travada por hash, então um índice comprometido ou uma wheel trocada em silêncio é recusada em vez de instalada (docs/security.md, cadeia de suprimentos). O Pango, dependência nativa do WeasyPrint, vem dos pacotes da sua distribuição, listados em Pré-requisitos.

O sidecar lê seu token de /etc/peart/render.env, como PEART_RENDER_TOKEN, e esse valor precisa ser igual ao render.token do config.yaml; a unit fornece o diretório de trabalho, host e porta (/var/lib/peart/work, 127.0.0.1:8090). A ADR 0005 exige WeasyPrint 68.0 ou mais novo por causa da CVE-2025-68616, e o app.py confere a versão em tempo de execução, então rebaixar só o arquivo de requisitos não basta para rodar uma versão velha: o sidecar recusa subir.

Ao atualizar o PEART, refaça este diretório a partir da mesma tag e reinstale os requisitos, para o sidecar não descolar dos binários que o chamam.

Próximos passos

1. Primeira execução e configuração, o arquivo de config, os caminhos que o PEART lê e escreve, e a chave mestra de cifragem gerada no primeiro boot.
2. Rodar como serviço (systemd), as units de deploy/systemd/, incluindo o isolamento de rede obrigatório do sidecar de renderização.
3. TLS e proxy reverso.

O sidecar de renderização é obrigatório, e o isolamento de rede dele não é opcional. Não rode uma instalação real a partir de make run; esse caminho local existe para desenvolvimento e omite o isolamento que as units de systemd carregam.