Como hospedar o open-kritt com segurança em um VPS

Por que executar open-kritt num VPS e não no seu laptop

Execute open-kritt num servidor que possa destruir e reconstruir. A ferramenta executa os seus agentes de análise como root dentro de contentores de tarefas descartáveis, fornece a cada agente uma cópia gravável do seu código e acesso direto à Internet, e monta o socket Docker do host no seu serviço de engine. Esta é uma permuta razoável num sistema dedicado à tarefa. É uma má escolha na máquina que armazena as suas chaves SSH.

Quatro propriedades da configuração predefinida justificam esta recomendação, e todas constam do README e do ficheiro compose do projeto.

Os agentes foram concebidos para ter amplos privilégios. O README indica que os agentes com ferramentas executam como root dentro de contentores de tarefas descartáveis, com cópias graváveis dos repositórios e acesso direto à Internet. Assim, podem instalar ferramentas, compilar alvos, executar testes e criar provas de conceito. Uma análise não é um linter que apenas lê ficheiros. É execução arbitrária de código que solicitou. Esse acesso à Internet pode ser usado nos dois sentidos: qualquer conteúdo que um agente obtenha ao investigar um alvo é texto não confiável que entra no seu prompt. É a mesma exposição que aceita quando fornece a um agente a sua própria pesquisa na Web.

O engine tem acesso ao socket Docker. docker-compose.yml monta o socket Docker do host no serviço de engine, porque o engine cria e inicia um contentor de análise por tarefa. Qualquer processo que consiga aceder a esse socket pode iniciar um contentor que monte o sistema de ficheiros do host. Portanto, o engine tem, na prática, privilégios root no host onde é executado.

Não existe um ecrã de início de sessão. O backend é distribuído sem autenticação da aplicação. Ter acesso à porta significa ter acesso aos seus resultados e aos créditos do seu fornecedor.

O código analisado muitas vezes não é seu. Apontar os agentes para um repositório de terceiros significa executar o processo de compilação desse repositório na sua máquina, como root e com acesso à rede.

Se leu por que os agentes de programação devem ficar numa VM descartável, este é o mesmo modelo de ameaça, mas mais forte. Forneça ao open-kritt um VPS sem outros serviços e administre esse VPS a partir de uma conta de utilizador separada com privilégios mínimos, em vez de usar root.

O que o open-kritt faz na prática

O open-kritt (o repositório é Kritt-ai/open-kritt e está licenciado sob AGPL-3.0) divide a pesquisa de vulnerabilidades em tarefas pequenas, executa essas tarefas em paralelo com agentes de IA e, em seguida, elimina duplicados e classifica os resultados. Define um workflow como uma cadeia de prompts específicos, e cada etapa recebe contexto estruturado das etapas anteriores. O alvo da análise é um repositório git remoto ou local. O mecanismo de análise é Codex ou Claude Code. Quando surge um candidato, scripts posteriores opcionais podem tentar validá-lo ou criar uma prova de conceito.

No final, obtém uma lista classificada de candidatos. Trate-a como uma fila de triagem, não como um relatório.

O que é necessário antes de começar

• Uma VPS com Ubuntu 24.04, Debian 12 ou Rocky Linux 9. A documentação de instalação lista essas distribuições como testadas, em x86_64 e ARM64.
• Docker Engine com o plugin Compose.
• Node.js 20 ou mais recente no host, porque a CLI ./kritt é executada no host, e não dentro de um contentor.
• Um fornecedor de modelos: um login do Codex ou OPENAI_API_KEY, CODEX_API_KEY, ANTHROPIC_API_KEY ou OPENROUTER_API_KEY.
• GITHUB_TOKEN apenas se pretender analisar repositórios privados. O .env.example fornecido declara isso claramente: um token do GitHub, por si só, não permite executar análises.

Instale primeiro o Docker e o Node 20

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

Termine a sessão e inicie-a novamente para aplicar a nova associação ao grupo. Em seguida, confirme que o plugin Compose está disponível.

docker compose version

Uma cadeia de versão indica que o Compose está instalado como plugin. docker: 'compose' is not a docker command indica que tem, em vez disso, o binário autónomo antigo docker-compose, e o open-kritt chama docker compose. A associação ao grupo docker equivale a root no host. Por isso, adicione-lhe apenas a conta que executa o open-kritt. Para obter a configuração completa, consulte executar o Docker numa VPS.

O Ubuntu 24.04 disponibiliza o Node 18 no seu próprio repositório, mas a CLI termina com qualquer versão inferior à 20. Use o NodeSource.

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v

node -v deve apresentar v20. ou superior. No Rocky Linux 9, o equivalente é sudo dnf module enable nodejs:20 -y seguido de sudo dnf install -y nodejs.

Clonar o open-kritt e fixar uma release marcada

git clone https://github.com/Kritt-ai/open-kritt
cd open-kritt
git fetch --tags
git tag --list
git checkout v1.3.0

main move-se consigo. Uma tag não. Em agosto de 2026, a tag mais recente é v1.3.0, publicada em 4 de agosto de 2026, e git tag --list mostra o que existe no dia em que faz o clone. Fazer checkout de uma tag deixa o repositório no estado HEAD destacado, o que é correto neste caso: está a tratar este clone como uma implementação fixada, não como uma branch na qual irá fazer commits. Para atualizar mais tarde, leia as notas da release, execute git fetch --tags, faça checkout da nova tag e execute ./kritt start novamente, porque start recompila as imagens.

Não execute ./kritt com sudo. A documentação é explícita sobre isso. A CLI gere diretórios de credenciais locais do projeto em .data/. Uma execução como root deixa esses diretórios pertencentes a root, e a execução normal seguinte não consegue escrever neles.

Configurar o acesso aos modelos com ./kritt setup

./kritt setup

O comando cria .env a partir de .env.example quando o ficheiro não existe, apresenta o estado de cada credencial e permite defini-las ou removê-las. Nunca apresenta os valores no terminal. Tanto .env como o ficheiro de credenciais do motor são gravados com o modo 0600.

Se preferir fazer isto manualmente:

cp .env.example .env
chmod 600 .env
mkdir -p .data/codex
chmod 700 .data/codex

Depois, edite a chave do fornecedor em .env e mantenha o ficheiro com o modo 0600. De qualquer forma, passa a existir uma credencial válida do fornecedor nesse servidor. Por isso, há mais uma razão para não manter nesse servidor mais nada. Crie uma chave exclusiva para este projeto, para que a sua revogação posterior não interrompa nada importante. Manter os segredos fora do alcance dos agentes de IA aborda esta prática de forma mais ampla.

Defina um limite de gastos do provedor antes da primeira análise

O open-kritt foi desenvolvido para distribuir tarefas, e é essa distribuição que gera custos. Os valores predefinidos em .env.example na v1.3.0 são conservadores: ENGINE_WORKER_COUNT=2, descrito no ficheiro como um valor predefinido conservador para uma máquina pequena com 2-vCPU, e ENGINE_MAX_CONCURRENT_SCANS=1. Acima deles estão ENGINE_WORKERS_PER_ACCOUNT=15, o número máximo de chamadas simultâneas ao modelo principal permitidas numa conta de provedor, e ENGINE_CODEX_MAX_SUBAGENTS_PER_SESSION=5, porque uma sessão do Codex pode executar até cinco agentes filhos. Se aumentar o número de workers numa VPS maior, o número de chamadas ao modelo em execução também aumenta.

Nada no repositório limita o valor que pode gastar. Não existe uma definição de orçamento em .env.example. As próprias condições de paragem do motor são esses limites de workers e ENGINE_HARNESS_TIMEOUT_SECONDS, que tem como valor predefinido 7200 segundos por execução do harness. Por isso, o limite tem de ser definido no provedor. Abra a consola do provedor e defina um limite mensal rígido antes da primeira análise, não depois. Controle os custos de um agente de IA numa VPS explica as definições de cada provedor.

Também existe um mecanismo de travagem local. Definir ENGINE_WORKER_COUNT=0 pausa a recolha de novos jobs, e os mesmos valores de workers podem ser alterados no ecrã Settings depois de a stack estar em execução.

Este guia não indica um preço por análise, porque o custo depende do tamanho do repositório, do workflow que criar e do modelo utilizado. Execute uma análise num repositório pequeno e, em seguida, consulte a página de utilização do provedor antes de o utilizar com algo maior.

Inicie a stack e confirme que está saudável

./kritt start

Isto verifica .env e pelo menos uma credencial e, em seguida, executa docker compose up --build. A primeira compilação é lenta porque compila as imagens do frontend, backend, engine, executor view e base de dados. Também é executada em primeiro plano, por isso fechar a sessão SSH interrompe a stack. Inicie-a dentro de tmux ou coloque-a em segundo plano depois de a primeira compilação ter sido concluída. Nenhuma destas opções sobrevive por si só a um reboot. Para voltar a iniciar a stack depois de o servidor reiniciar, o padrão de unidade systemd em manter um agente self-hosted em execução após reboots aplica-se diretamente.

docker compose up -d --build
docker compose ps

docker compose ps deve listar open-kritt-frontend, open-kritt-backend, open-kritt-engine, open-kritt-executor-view e open-kritt-db. Em seguida, verifique se o backend responde no próprio servidor.

curl -s http://127.0.0.1:3002/api/health

Uma resposta JSON significa que o backend está em execução. Failed to connect to 127.0.0.1 port 3002: Connection refused significa que não está, e docker compose logs backend indicará o motivo. Pare tudo com docker compose down a partir do diretório do repositório.

Uma opção adicional: docker compose exec backend npm run seed carrega dados de demonstração. Esta é uma forma simples de consultar a interface antes de gastar recursos numa análise real.

Aceda à interface na porta 5173 através de um túnel SSH

Todos os serviços no ficheiro compose estão associados a 127.0.0.1 por predefinição: o frontend na porta 5173, o backend na porta 3002, a vista do executor na porta 8090 e o Postgres na porta 5432. Mantenha essas associações e reencaminhe a porta por SSH a partir da sua própria máquina.

ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip

Abra http://localhost:5173 no navegador local enquanto esse comando estiver em execução. -N significa que a ligação transporta o reencaminhamento e não abre uma shell. Adicione um segundo -L 8090:127.0.0.1:8090 ao mesmo comando quando também quiser a vista do executor.

A tentação é definir FRONTEND_BIND_ADDRESS=0.0.0.0 e ignorar o túnel. Não faça isso. O backend não tem ecrã de início de sessão, por isso qualquer pessoa que aceda a essa página pode iniciar análises e consumir o crédito do seu fornecedor. Existe outra armadilha: uma porta de contentor publicada é processada antes de a política predefinida do ufw ser aplicada, por isso uma regra ufw deny 5173 parece correta, mas não bloqueia nada. Portas Docker que contornam o ufw mostra a cadeia de regras que causa esse comportamento.

Dimensionamento do VPS

ENGINE_MIN_FREE_STORAGE_GB é 20 por padrão, e o engine recusa iniciar um novo contentor de scan por tarefa quando o armazenamento livre fica abaixo desse valor. As imagens compiladas, a cache dos checkouts, os dados do Postgres e os espaços de trabalho das tarefas ficam todos no mesmo disco, por isso um VPS de 20 GB nunca inicia um scan. Considere 40 GB como o mínimo e atribua mais espaço se analisar repositórios grandes.

A memória segue uma aritmética simples. ENGINE_MEMORY_RESERVE_GB=2 reserva memória para o engine, a base de dados, a API e a sobrecarga temporária, e cada runner de scan tem uma reserva e um limite rígido de ENGINE_SCAN_RUNNER_MEMORY_MB=1536. Dois workers precisam, portanto, de cerca de 5 GB antes de qualquer outro processo arrancar. O engine só inicia os runners que cabem no orçamento restante. Num servidor pequeno, os scans ficam em fila em vez de falharem. Este comportamento é muito melhor do que a intervenção do out-of-memory killer.

Duas definições de prune têm o valor true por padrão: ENGINE_AUTO_PRUNE_DOCKER_BUILD_CACHE e ENGINE_AUTO_PRUNE_UNUSED_DOCKER_IMAGES. Depois de uma tarefa terminar, o engine remove a cache de build não utilizada, as imagens não utilizadas e os contentores de scan parados. As imagens referenciadas por um contentor em execução, os bind mounts, os dados da base de dados, as credenciais e os volumes são preservados. Ainda assim, esta é mais uma razão para não partilhar o host: um pruner que não configurou está a executar operações nesse Docker daemon.

Verificar um repositório local sem o expor

LOCAL_REPOS_PATH utiliza ./local_repos por predefinição e é montado como bind mount nos contentores de backend e do engine em /local_repos. Assim, um repositório colocado nessa pasta do host aparece imediatamente dentro dos contentores. Utilize um clone novo, não a sua árvore de trabalho. O contentor do job recebe uma cópia com permissões de escrita, executa como root no seu próprio ambiente e tem acesso à Internet de saída. Isto significa que qualquer conteúdo nessa cópia pode ser alterado ou enviado para fora do servidor. Remova os ficheiros .env e as chaves privadas antes de copiar um projeto para lá.

O que recebe e o que não recebe

Você recebe descobertas candidatas classificadas. Não recebe vulnerabilidades verificadas. A classificação e a eliminação de duplicados definem a ordem da sua fila de triagem. Não provam que uma entrada é real. Os post-scripts podem tentar validar a descoberta e criar uma prova de conceito. Esse é o sinal mais forte oferecido pela ferramenta. No entanto, um post-script que falha não prova que a descoberta é falsa. Uma pessoa ainda lê cada candidato.

Este guia não afirma quantos bugs reais o open-kritt encontra, porque não fizemos essa medição. Quem citar uma taxa de deteção para a sua base de código não executou a ferramenta nessa base de código. Comece por analisar um repositório que já conheça bem. As descobertas que consegue avaliar por si são a forma mais barata de calibrar a ferramenta.

A autorização é mais importante neste caso do que na maioria das ferramentas alojadas localmente. Os agentes compilam e executam código e acedem à rede, pelo que uma etapa de prova de conceito pode interagir com sistemas em produção. Aponte a ferramenta para código que lhe pertença ou que esteja autorizado contratualmente a testar. Registe o âmbito do alvo antes de executar qualquer operação. Se configurar ANTHROPIC_API_KEY e utilizar o motor Claude Code, os procedimentos de sandboxing descritos em executar o Claude Code com segurança num VPS também se aplicam a estes agentes.

FAQ

Por que o open-kritt precisa do seu próprio VPS?

Porque os agentes de análise executam como root dentro de contentores de tarefas descartáveis, com cópias graváveis do seu código e acesso direto à Internet. Além disso, o serviço do motor monta o socket Docker do host para poder iniciar um contentor por tarefa. Qualquer processo que alcance esse socket pode iniciar um contentor que monte o sistema de ficheiros do host. Por isso, toda a stack deve ser tratada como root no respetivo host. Num VPS dedicado, esta é uma troca aceitável, e reconstruir o servidor não lhe custa nada. Na sua estação de trabalho diária, as chaves SSH e os perfis do navegador ficam no mesmo limite de confiança que o código que está a analisar.

Posso expor a porta 5173 em vez de usar um túnel SSH?

Não deve fazê-lo. O backend é disponibilizado sem autenticação da aplicação. Assim, a porta é a única barreira entre a Internet, os resultados da análise e o crédito do fornecedor. Por esse motivo, o ficheiro compose associa todos os serviços a 127.0.0.1. Execute ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip e aceda localmente a http://localhost:5173. Uma regra do ufw não substitui esta proteção, porque uma porta publicada pelo Docker é processada antes de a política predefinida do ufw ser aplicada.

Como impeço o open-kritt de gastar mais do que planeei?

Defina um limite rígido na consola do seu fornecedor de modelos antes da primeira análise, porque o open-kritt não tem uma definição própria de orçamento. Mantenha os valores predefinidos de concorrência disponibilizados inicialmente nas primeiras execuções, ENGINE_WORKER_COUNT=2 e ENGINE_MAX_CONCURRENT_SCANS=1. Tenha presente que, por predefinição, uma conta de fornecedor permite até 15 chamadas concorrentes ao modelo root, enquanto uma sessão Codex pode executar até cinco agentes-filhos. ENGINE_WORKER_COUNT=0 interrompe a recolha de novas tarefas e é a forma mais rápida de parar localmente.

Que versão devo obter?

Uma tag, nunca main. git fetch --tags seguido de git tag --list mostra o que está disponível, e v1.3.0, publicado em 4 August 2026, é a versão mais recente no momento desta redação. Fixar uma versão garante que uma reconstrução feita meses mais tarde produz a mesma stack. Também transforma a atualização numa decisão tomada depois de ler as notas de versão, em vez de num efeito secundário de clonar o repositório num dia diferente.

Uma análise nunca começa. O que devo verificar?

Verifique primeiro o espaço livre em disco, porque o motor não inicia um contentor de análise separado por tarefa quando o armazenamento livre é inferior a ENGINE_MIN_FREE_STORAGE_GB, cujo valor predefinido é 20 GB. Depois, confirme que ENGINE_WORKER_COUNT não é 0, porque esse valor interrompe a recolha de novas tarefas. Em seguida, confirme que uma credencial de modelo está realmente configurada executando ./kritt setup, porque um GITHUB_TOKEN, por si só, não consegue executar análises. docker compose logs engine indica o motivo pelo qual a tarefa foi ignorada.