Agentes autônomos de pentest com IA — reconhecimento em tempo real, detecção de vulnerabilidades e orquestração de exploração. Go + TypeScript.
<div align="center">
<img src="https://raw.githubusercontent.com/xalgord/xalgorix/main/assets/banner.png?v=4.6.133" alt="Xalgorix — Plataforma Autónoma de Testes de Penetração com IA" width="860" />
<br />
[](https://go.dev)
[](LICENSE)
[](#-installation)
[](https://www.xalgorix.com/)
[](https://github.com/xalgorix/xalgorix/stargazers)
[](https://github.com/xalgorix/xalgorix/network/members)
[](https://github.com/xalgorix/xalgorix/releases)
[](https://deepwiki.com/xalgorix/xalgorix)
</div>
<h1 align="center">Xalgorix — Pentester de IA open-source que <em>prova</em> vulnerabilidades</h1>
<p align="center">
<strong>A maioria dos scanners deteta. O Xalgorix prova.</strong> Um agente LLM autónomo segue uma metodologia completa de pentest e, em seguida, um <strong>verificador independente re-explora cada descoberta</strong> antes de esta ser reportada — para que obtenha provas, e não uma pilha de incertezas para triagem. Auto-hospedado, privado e com o seu próprio LLM. Construído em Go + TypeScript.
</p>
<p align="center">
<a href="#-quick-start">🚀 Início Rápido</a> ·
<a href="#-why-xalgorix">💡 Porquê o Xalgorix</a> ·
<a href="#-features">✨ Funcionalidades</a> ·
<a href="#-use-cases">🎯 Casos de Uso</a> ·
<a href="https://www.xalgorix.com/">☁️ Cloud Hospedado</a> ·
<a href="https://docs.xalgorix.com">📖 Documentação</a>
</p>
---
## 🎬 Visão Geral do Lançamento
<div align="center">
[](https://youtu.be/B23boh51u8A)
**▶️ [Veja o vídeo de lançamento de 50 segundos](https://youtu.be/B23boh51u8A)** — O Xalgorix em ação: análise autónoma e descobertas verificadas por exploração em menos de um minuto.
</div>
---
## 📸 Capturas de Ecrã
**🖥️ Painel auto-hospedado** — é executado localmente em `127.0.0.1:9137`
| Painel de visão geral | Detalhe da análise | Descobertas |
| ------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------- |
|  |  |  |
**☁️ Painel cloud hospedado** — a versão totalmente gerida em [www.xalgorix.com](https://www.xalgorix.com/)
<img src="https://raw.githubusercontent.com/xalgord/xalgorix/main/assets/SaaS-dashboard.png?v=4.5.154" alt="Xalgorix hosted cloud dashboard showing security score, vulnerability trends, remediation metrics, and open issues by category" width="860" />
---
## 🤝 Patrocinadores
Obrigado à **[Swiftproxy](https://www.swiftproxy.net/?ref=xalgorix)** por patrocinar o Xalgorix.
<a href="https://www.swiftproxy.net/?ref=xalgorix">
<img src="https://raw.githubusercontent.com/xalgord/xalgorix/main/assets/swiftproxy_xalgorix.webp" alt="Swiftproxy sponsors Xalgorix — residential proxies for authorized testing across locations" width="860" />
</a>
A sua aplicação pode comportar-se de forma diferente consoante a origem de um pedido. Para os utilizadores do Xalgorix que verificam as suas próprias aplicações em várias regiões, a Swiftproxy oferece **segmentação por localização** para analisar o comportamento regional e **sessões persistentes** para ajudar a manter um IP consistente durante uma sessão de teste. Suporta **HTTP(S) e SOCKS5**, os mesmos protocolos de proxy que o Xalgorix suporta.
Proxies residenciais a partir de **$0.70/GB**. **Testes gratuitos disponíveis**, e os utilizadores do Xalgorix têm **10% de desconto** com o código **`PROXY90`**.
[**Explore a Swiftproxy e solicite um teste gratuito →**](https://www.swiftproxy.net/?ref=xalgorix)
---
## 🚀 Início Rápido
**Instalação (uma linha):**
```bash
curl -sSL https://www.xalgorix.com/install | bash
```
Isso baixa o binário pré-compilado para a sua plataforma (Linux ou macOS, amd64/arm64) a partir da versão mais recente.
**Ou instale com Go 1.26 ou mais recente:**
```bash
go install github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest
```
Certifique-se de que `$(go env GOPATH)/bin` (ou seu `GOBIN`) esteja no seu `PATH` antes de executar o `xalgorix`.
Em seguida, execute o assistente de configuração interativo:
```bash
xalgorix --setup
```
Escolha o seu provedor, confirme um modelo e insira a chave de API quando solicitado. Para melhores resultados, use um modelo de fronteira atual com raciocínio forte, desempenho de contexto longo e chamada de ferramentas confiável — como o modelo GPT, Claude ou Gemini mais recente e capaz disponível para você. Modelos menores ou locais continuam suportados, mas podem exigir mais supervisão durante varreduras autônomas longas. O Xalgorix armazena a chave de forma privada em `~/.xalgorix.env` (modo `0600`) e pode iniciar o painel para você. O Ollama local não precisa de chave de API.
Se você optar por não iniciar imediatamente, inicie depois com `xalgorix --web` e abra `http://127.0.0.1:9137`. Você pode alterar provedores ou opções avançadas a qualquer momento em **Settings → LLM**, ou executar novamente `xalgorix --setup`.
**Ou execute com Docker — tudo incluído, sem necessidade de toolchain:**
```bash
docker run --rm -p 9137:9137 \
--privileged \
-v xalgorix-data:/data \
xalgord/xalgorix:latest
```
`--privileged` concede ao toolset o mesmo acesso tipo host que ele tem quando executado nativamente como root. O sandbox padrão do Docker remove capacidades (como `NET_ADMIN`) e aplica um filtro seccomp, o que quebra ferramentas de baixo nível (alterações de iptables/route, ARP-spoof/MITM, VPNs tun/tap, depuradores baseados em ptrace, ajuste de interface do masscan). Como uma imagem não pode conceder isso a si mesma, elas devem ser definidas em tempo de execução. O contêiner é um sandbox de varredura descartável e isolado de rede executando como root — privileged é a postura pretendida; nunca exponha o dashboard publicamente sem autenticação. Prefere privilégio mínimo? Troque `--privileged` por `--cap-add=NET_ADMIN --cap-add=NET_RAW --cap-add=SYS_PTRACE --security-opt seccomp=unconfined`.
Abra `http://localhost:9137`. Você **não precisa de uma chave de LLM para começar** — o dashboard inicia sem uma; defina o modelo + chave de API em **Settings → LLM** (ela persiste no volume `/data`). Se você não passar `XALGORIX_USERNAME`/`XALGORIX_PASSWORD`, uma senha de admin aleatória é gerada e impressa nos logs do contêiner na primeira execução.
**Acesso à API máquina-a-máquina** — dê à automação (seu próprio backend, CI, scripts) um token dedicado `Authorization: Bearer` em vez de credenciais do dashboard: defina `XALGORIX_API_TOKEN` (ou `XALGORIX_API_TOKENS` para um conjunto de rotação separado por vírgulas). Tokens de máquina autorizam rotas `/api/*` e apenas o WebSocket de eventos de varredura — nunca a UI do dashboard ou rotas de configurações exclusivas de operador — nunca criam sessões de navegador, nunca interagem com o limitador de taxa de login do dashboard, e são comparados com digests SHA-256 armazenados usando comparação de tempo constante. O login humano do dashboard (`XALGORIX_USERNAME` + `XALGORIX_PASSWORD_HASH`) continua funcionando inalterado ao lado deles.
**Mais fácil — Docker Compose** (mapeia a porta + um volume persistente para você):
```bash
curl -sSLO https://raw.githubusercontent.com/xalgorix/xalgorix/main/docker-compose.yml
docker compose up -d
docker compose logs -f # shows the generated admin password on first start
```
A imagem já vem com um extenso conjunto de ferramentas de segurança ofensiva pré-instaladas (nmap, nuclei, httpx, subfinder, katana, ffuf, gobuster, sqlmap, masscan, dalfox, feroxbuster, e mais) **e** mantém todos os gestores de pacotes (apt, go, cargo, pipx, npm) disponíveis para que o agente ainda possa instalar automaticamente qualquer coisa em falta em tempo de execução. É executado como root dentro do contentor por design — trate o contentor como uma sandbox de scanning descartável e isolada da rede e nunca exponha o dashboard sem autenticação. As imagens são publicadas tanto para amd64 como para arm64.
**Ou compile a partir do código-fonte** (requer Go 1.26+ e Node.js):
```bash
git clone https://github.com/xalgorix/xalgorix.git
cd xalgorix
make build
sudo install -m 755 build/xalgorix /usr/local/bin/xalgorix
```
> [!TIP]
> Prefere configuração zero? Uma versão totalmente gerenciada roda em [www.xalgorix.com](https://www.xalgorix.com/) — clique para escanear, sem instalação ou chaves de API necessárias.
### 🤖 Revise pull requests automaticamente — GitHub App gratuito
Quer uma revisão de segurança em cada pull request com configuração zero? Instale o **[Xalgorix GitHub App](https://github.com/apps/xalgorix)**. Ele lê o diff de cada PR e comenta uma revisão de segurança — injeção, autenticação quebrada/IDOR, SSRF, segredos, padrões inseguros — diretamente no pull request. Atualiza no lugar em novos commits, e você pode comentar **`@xalgorix review`** para reexecutar sob demanda. Sem arquivo de workflow, sem chave de API, sem conta — e é gratuito.
<div align="center">
[**➕ Adicionar Xalgorix ao GitHub →**](https://github.com/apps/xalgorix/installations/new)
</div>
Para merge gating e pentests completos com exploits verificados em CI, use o [scanner hospedado](https://www.xalgorix.com/) ou a GitHub Action.
> [!IMPORTANT]
> Use o Xalgorix apenas em sistemas que você possui ou tem permissão explícita para testar.
> [!TIP]
> Prefere não auto-hospedar? Uma versão totalmente gerenciada está disponível em [www.xalgorix.com](https://www.xalgorix.com/) — clique para escanear, sem instalação ou chaves de API necessárias.
## 📚 Conteúdo
| | | |
| --- | --- | --- |
| 📸 [Capturas de tela](#-screenshots) | 🔩 [Configuração](#-configuration) | 🧾 [Variáveis de ambiente](#-environment-variables) |
| 🎬 [Visão geral do lançamento](#-launch-overview) | 🚀 [Início rápido](#-quick-start) | 🆙 [Atualização](#-upgrading-from-previous-versions) |
| 🔎 [Visão geral](#-overview) | 🏃 [Execução](#-running) | 🔤 [Prefixos de provedor](#-provider-prefixes) |
| 💡 [Por que Xalgorix](#-why-xalgorix) | 🧰 [Modo de serviço](#-service-mode) | 💻 [Referência da CLI](#-cli-reference) |
| 🎯 [Casos de uso](#-use-cases) | 🔁 [Fluxo de trabalho da Web UI](#-web-ui-workflow) | 📡 [Resumo da API](#-api-summary) |
| 🎯 [Casos de uso](#-use-cases) | 🔁 [Fluxo de trabalho da Web UI](#-web-ui-workflow) | 💾 [Armazenamento de dados](#-data-storage) |
| ✨ [Recursos](#-features) | 🔀 [Modos de varredura](#-scan-modes) | 🧪 [Desenvolvimento](#-development) |
| 📥 [Instalação](#-installation) | 📂 [Escaneie seu código](#-scan-your-code-no-target-needed) | 🚨 [Notas de segurança](#-safety-notes) |
| 🧭 [Metodologia](#-methodology) | 📄 [Relatórios](#-reports) | 📜 [Licença](#-license) |
| 🔧 [Configurações](#-settings) | 🔗 [Links](#-links) | 🤝 [Patrocinadores](#-sponsors) |
## 🔎 Visão geral
Xalgorix é uma plataforma de teste de penetração com IA auto-hospedada para testes de segurança autorizados, avaliação de vulnerabilidades e fluxos de trabalho de bug bounty. Ela combina um agente autônomo orientado por LLM, automação de navegador, ferramentas de terminal, uma metodologia abrangente de testes em 22 fases, telemetria ao vivo via WebSocket, gerenciamento de achados com pontuação CVSS, geração de relatórios PDF com marca e integrações para AgentMail, Discord e Telegram.
Diferente de scanners DAST apenas em nuvem, o Xalgorix roda inteiramente na sua máquina. Você traz seu próprio provedor de LLM (OpenAI, Anthropic, DeepSeek, Gemini, Groq, Ollama, MiniMax) e controla o modelo, esforço de raciocínio, limites de taxa e configuração de proxy. Nenhum dado de varredura, chave de API ou informação de alvo sai da sua infraestrutura.
A experiência padrão é a Web UI. A partir de um único painel local você pode iniciar varreduras, monitorar execuções ativas, inspecionar achados, configurar ajustes de modelo/provedor, gerenciar variáveis de ambiente, gerar relatórios PDF com marca e excluir ou retomar varreduras históricas.
## 💡 Por que Xalgorix
A maioria dos scanners **detecta**. Xalgorix **prova**. Um agente autônomo trabalha através de uma metodologia de 22 fases, então um verificador independente retesta cada achado candidato antes de ser reportado — assim você obtém resultados com exploits verificados e evidências, não uma parede de "talvez" para triagem.
- 🧠 **Um agente de IA, não um motor de templates** — raciocina sobre fluxos de autenticação, lógica de negócios, IDOR/BOLA e exploits encadeados que scanners de assinatura perdem.
- ✅ **Achados com exploits verificados** — um verificador separado reproduz independentemente cada achado; os inconclusivos são sinalizados para revisão, nunca disfarçados como confirmados.
- 🔒 **Auto-hospedado e privado** — roda na sua máquina com sua própria chave de LLM; nenhum dado de alvo, chave ou achado sai da sua infraestrutura.
- 🧩 **Traga seu próprio LLM** — OpenAI, Anthropic, DeepSeek, Gemini, Groq, Ollama ou MiniMax — ou qualquer gateway compatível com OpenAI como [LiteLLM](#-litellm--openai-compatible-gateways-github-copilot-claude-opus-codex-openrouter-azure-local-models) (GitHub Copilot, Codex, OpenRouter, Azure). Você controla modelo, esforço de raciocínio e custo.
- 📄 **Relatórios prontos para auditoria** — PDFs com marca, pontuações CVSS, prova de conceito e remediação.
### 📊 Como se compara
| | **Xalgorix** | Scanners de template (ex.: Nuclei) | Scanners de crawling (ex.: OWASP ZAP) | DAST comercial |
| -------------------------------------------- | ------------------------ | ------------------------------- | ---------------------------------- | ---------------------- |
| Abordagem | Agente de IA autônomo | Assinaturas / templates | Spider + regras ativas | Assinaturas + heurísticas |
| Cobertura de lógica de negócios / IDOR / bypass de autenticação | ✅ | Limitada | Limitada | Parcial |
| Exploit verificado (prova o impacto) | ✅ verificador independente | ❌ | ❌ | Parcial |
| Carga de falsos positivos | Baixa (comprovado) | Depende do template | Alta | Média |
| Auto-hospedado / dados permanecem locais | ✅ | ✅ | ✅ | Geralmente nuvem |
| Traga seu próprio LLM | ✅ | — | — | ❌ |
| Relatórios PDF com marca | ✅ | ❌ | Básico | ✅ |
| Custo | Código aberto + seu LLM | Gratuito | Gratuito | $$$ |
> Comparação direcional — Nuclei e ZAP são excelentes no que fazem. Xalgorix adiciona a camada de descoberta com raciocínio pesado e verificação de exploits por cima.
### ☁️ Auto-hospedado vs Nuvem hospedada
Xalgorix é gratuito e de código aberto — auto-hospede para sempre, sem compromissos. A [nuvem hospedada](https://www.xalgorix.com/) roda o **mesmo** motor com exploits verificados; ela existe para pessoas que preferem não gerenciar chaves de API, infraestrutura e contas imprevisíveis de LLM. Ambos são de primeira classe — escolha o que se encaixa.
| | **Auto-hospedado** (este repositório) | **[Nuvem hospedada](https://www.xalgorix.com/)** |
| ---------------------------------- | ---------------------------------------- | ----------------------------------------------- |
| Preço para começar | Motor gratuito, Apache-2.0 | [Pacotes de créditos ou assinaturas](https://www.xalgorix.com/pricing) |
| Chave de API do LLM | Traga e gerencie a sua | Incluída — nada para gerenciar |
| Custo por varredura | Tokens brutos de LLM — variável, pode disparar | Baseado em créditos; veja [preços atuais](https://www.xalgorix.com/pricing) |
| Configuração e operações | Você instala, atualiza e executa o toolchain | Nada para executar — escaneie em ~60s |
| Infraestrutura out-of-band (SSRF/blind RCE) | Monte seu próprio servidor OOB | OOB gerenciado incluído |
| Agendamento | Agendador integrado na sua infraestrutura | Agendamentos diários / por hora gerenciados |
| Equipe · RBAC · créditos compartilhados | Instância de operador único | Workspaces de organização em Teams / Enterprise |
| Atualizações | `git pull` + rebuild | Sempre no motor mais recente |
| Residência de dados / offline | ✅ permanece na sua infra · air-gap OK | Roda na nossa infra (DPA disponível) |
**Auto-hospede se** os dados precisam permanecer na sua rede, você quer controle total, ou vai rodar offline/air-gapped — é exatamente para isso que serve. **Use a nuvem se** você prefere pular as chaves de API, infraestrutura e contas surpresa de tokens, e pagar apenas pelos hosts ativos que realmente escaneia.
<div align="center">
[**☁️ Explore os planos da Nuvem hospedada →**](https://www.xalgorix.com/pricing) · [**⚖️ Compare Nuvem e auto-hospedagem →**](https://www.xalgorix.com/hosted-vs-self-hosted)
</div>
Se o Xalgorix economiza um ciclo de triagem para você, por favor **[⭐ dê uma estrela no repositório](https://github.com/xalgorix/xalgorix)** — isso genuinamente ajuda outros a encontrá-lo.
## 🎯 Casos de uso
| Caso de uso | Como o Xalgorix ajuda |
| -------- | ------------------ |
| **Teste de penetração** | Execute uma metodologia completa de 22 fases contra alvos autorizados. O agente de IA cuida de reconhecimento, descoberta de vulnerabilidades, testes de injeção, SSRF, IDOR, bypass de autenticação, condições de corrida e mais — depois verifica os achados antes de reportar. |
| **Caça a bug bounty** | Aponte o Xalgorix para um alvo no escopo e deixe o agente enumerar a superfície de ataque, testar classes comuns de vulnerabilidade e revelar achados verificados com pontuações CVSS e evidências de prova de conceito. |
| **Operações de red team** | Use os modos de varredura wildcard e multi-alvo para mapear a superfície de ataque externa de uma organização. O DAST assistido por navegador lida com fluxos de autenticação, formulários e comportamento em tempo de execução que scanners estáticos perdem. |
| **Pesquisa de segurança** | A fase de descoberta de vulnerabilidades inéditas leva o agente além da correspondência de templates conhecidos. Traga seu próprio LLM (OpenAI, Anthropic, DeepSeek, Gemini, Ollama, MiniMax) para controlar a profundidade de raciocínio e o custo. |
| **Teste de segurança contínuo** | Execute como um serviço de sistema com `xalgorix --start`. Escaneie em um agendamento, transmita achados para Discord ou Telegram e gere relatórios PDF com marca para stakeholders. |
| **Automação de DAST** | Testes orientados por navegador para aplicações web — fluxos de autenticação, formulários, conteúdo renderizado por JavaScript e comportamento em tempo de execução. Integra-se com Caido para inspeção de tráfego de proxy. |
## ✨ Recursos
| Área | Capacidades |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| 📊 Painel | Web UI local em `127.0.0.1:9137` por padrão, gerenciamento de varreduras, status ao vivo, ações de varredura em massa e recuperação de varreduras históricas. |
| 🔍 Varredura | Alvo único, DAST, wildcard e fluxos multi-alvo com fases de metodologia selecionáveis. |
| 📡 Telemetria ao vivo | Chamadas de ferramentas, mensagens do agente, achados, erros, atividade HTTP e atividade de LLM via WebSockets. |
| 🐞 Achados | Páginas de detalhes de varredura, filtros de severidade, detalhes de CVSS, índice de achados e fluxos de achados verificados. |
| 📄 Relatórios | Relatórios PDF com marca com nome do alvo/empresa, logo enviado, lista de relatórios, ações de abrir/baixar/excluir. |
| 🔔 Integrações | Caixas de entrada de teste do AgentMail, e-mails de verificação, fluxos de OTP, eventos de triagem de e-mail, notificações do Discord e Telegram. |
| ⚙️ Configuração | Configurações do painel para LLM, AgentMail, Discord, Telegram, proxy, runtime, navegador, autenticação, limites de taxa e recursos. |
| 🛡️ Segurança em tempo de execução | Limites de instância cientes de recursos e vinculação apenas em loopback, a menos que o acesso externo seja explicitamente configurado com autenticação. |
## 📥 Instalação
Use um binário pré-compilado, Go ou um contêiner.
### ⚡ Instalação em uma linha (binário pré-compilado)
```bash
curl -sSL https://www.xalgorix.com/install | bash
```
Baixa o binário da versão mais recente para a sua plataforma (Linux ou macOS, `amd64`/`arm64`) e instala-o em `/usr/local/bin` (ou `~/.local/bin` sem sudo). Substitua com `XALGORIX_INSTALL_DIR` ou fixe uma versão com `XALGORIX_VERSION=vX.Y.Z`.
Conclua a configuração inicial de forma interativa—sem necessidade de edição manual do ficheiro de ambiente:
```bash
xalgorix --setup
```
O assistente preserva as configurações existentes quando executado novamente, oculta a entrada da chave de API num terminal e, opcionalmente, inicia a interface Web quando termina.
### 📦 Instalar com Go
Com Go 1.26 ou mais recente:
```bash
go install github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest
```
O Go instala o binário em `GOBIN`, ou em `$(go env GOPATH)/bin` quando `GOBIN` não está definido. Adicione esse diretório ao seu `PATH` e, em seguida, execute `xalgorix --setup`.
### 🐳 Docker
```bash
docker run --rm -p 9137:9137 \
--privileged \
-e XALGORIX_LLM=openai/gpt-5.6 \
-e XALGORIX_API_KEY=your_openai_api_key \
-v xalgorix-data:/data \
ghcr.io/xalgord/xalgorix:latest
```
`--privileged` (ou o mais restrito `--cap-add=NET_ADMIN --cap-add=NET_RAW --cap-add=SYS_PTRACE --security-opt seccomp=unconfined`) concede ao conjunto de ferramentas acesso semelhante ao do host. O sandbox padrão do Docker remove capacidades e filtra syscalls, o que quebra ferramentas de baixo nível (alterações de iptables/route/interface, ARP-spoof/MITM, VPNs tun/tap, depuradores baseados em ptrace). Uma imagem não pode conceder isso a si mesma — é uma decisão de tempo de execução — então passe a flag, ou use o `docker-compose.yml` fornecido, que a define para você.
A imagem é **batteries-included**: um extenso conjunto de ferramentas de segurança ofensiva vem pré-instalado (nmap, nuclei, httpx, subfinder, dnsx, naabu, katana, ffuf, gobuster, dalfox, feroxbuster, sqlmap, masscan, nikto, whatweb, hydra, e mais), além do Chromium para DAST assistido por navegador. Ela também mantém o conjunto completo de gerenciadores de pacotes (apt, go, cargo, pipx, npm) disponível, então o agente instala automaticamente qualquer coisa que esteja faltando em tempo de execução. Os dados de varredura persistem no volume `/data`, e o servidor escuta em `0.0.0.0` dentro do contêiner — defina `XALGORIX_USERNAME`/`XALGORIX_PASSWORD` antes de expô-lo além do localhost.
O contêiner roda como root por design (o engine só habilita a instalação automática em tempo de execução para uid 0, e as instalações via apt/go/cargo precisam de acesso de escrita ao sistema). Trate-o como um sandbox de varredura descartável e isolado na rede. As mesmas tags publicam um manifesto multiplataforma para `linux/amd64` e `linux/arm64`, então o Docker seleciona a imagem nativa automaticamente.
Na primeira execução, se você não definir a autenticação do dashboard, o contêiner **gera uma senha de administrador aleatória e a imprime nos logs** (a imagem escuta em `0.0.0.0`, o que o engine não fará sem autenticação). Defina `XALGORIX_USERNAME` + `XALGORIX_PASSWORD` (ou `XALGORIX_PASSWORD_HASH`) para usar as suas próprias. O binário nunca se auto-atualiza dentro do contêiner (`XALGORIX_NO_AUTO_UPDATE=1`) — baixe uma nova tag de imagem para atualizar. O engine **nuclei** e seus templates de vulnerabilidade são atualizados para a versão mais recente a cada build da imagem (o CI de release e o `redeploy.sh` forçam isso); passe `--build-arg NUCLEI_VERSION=vX.Y.Z` para fixar o engine, ou `NUCLEI_REFRESH=0 ./redeploy.sh` para reutilizar o cache do Docker.
### ☸️ Kubernetes (Helm)
Um chart Helm está incluído no repositório em [`deploy/chart`](https://github.com/xalgord/xalgorix/blob/main/deploy/chart). Não há repositório de charts hospedado, então instale a partir de um checkout do git:
```bash
git clone https://github.com/xalgorix/xalgorix.git
cd xalgorix
helm install xalgorix deploy/chart \
--namespace xalgorix --create-namespace \
--set auth.username=admin \
--set auth.password=change-me \
--set env.secret.XALGORIX_LLM=openai/gpt-5.6 \
--set env.secret.XALGORIX_API_KEY=your_openai_api_key
```
- O dashboard escuta na porta `9137`. Exponha-o com `ingress.enabled` (controlador Ingress) ou `httproute.enabled` (Gateway API) — nunca sem autenticação do dashboard.
- Os dados de varredura e as configurações persistidas do dashboard ficam em um PVC montado em `/data` (consulte `persistence` em `values.yaml`). As configurações alteradas na UI de Configurações do dashboard são gravadas em `/data/.xalgorix.env` e têm precedência sobre as variáveis de ambiente fornecidas pelo chart na reinicialização.
- Qualquer variável `XALGORIX_*` pode ser passada por meio de `env.raw`, `env.config` ou `env.secret`. As credenciais do dashboard vão em `auth`, ou aponte `auth.existingSecret` para um Secret contendo `XALGORIX_USERNAME`/`XALGORIX_PASSWORD`.
- O conjunto de ferramentas incluído espera as mesmas permissões elevadas que a execução via Docker (`NET_ADMIN`, `NET_RAW`, `SYS_PTRACE`, seccomp `Unconfined`) — consulte os exemplos de `securityContext` em `values.yaml`.
### 📋 Requisitos (compilar a partir do código-fonte)
| Requisito | Observações |
| -------------- | ------------------------------------------------------------ |
| SO | Linux ou macOS (`amd64`/`arm64`). |
| Go | `1.26` ou mais recente. |
| Node.js + npm | Necessário ao compilar a UI Web React incluída a partir do código-fonte. |
| Ferramentas de segurança | Instaladas sob demanda apenas quando a instalação automática está habilitada. |
Verifique sua versão do Go:
```bash
go version
```
### 🔨 Compilar a Partir do Código-Fonte
```bash
git clone https://github.com/xalgorix/xalgorix.git
cd xalgorix
make build
sudo install -m 755 build/xalgorix /usr/local/bin/xalgorix
```
`make build` compila a React Web UI em `internal/web/static`, depois compila o binário Go.
## 🔩 Configuração
O Xalgorix carrega a configuração nesta ordem. Fontes posteriores substituem as anteriores.
| Ordem | Fonte |
| ----- | -------------------------------------------------------------- |
| 1 | `/etc/xalgorix.env` |
| 2 | `/home/<sudo-user>/.xalgorix.env` quando iniciado através de `sudo` |
| 3 | `~/.xalgorix.env` |
| 4 | Variáveis de ambiente já presentes no processo |
Crie o arquivo de ambiente local:
```bash
nano ~/.xalgorix.env
```
### 🧩 Configuração Mínima
Para obter os resultados de varredura autônoma mais robustos, selecione um modelo de fronteira atual. O ID do modelo abaixo é um exemplo concreto; IDs de modelos compatíveis mais recentes podem ser inseridos sem esperar por uma versão do Xalgorix.
```bash
XALGORIX_LLM=openai/gpt-5.6
XALGORIX_API_KEY=your_openai_api_key
```
### 🔌 Exemplos de Provedores
OpenAI:
```bash
XALGORIX_LLM=openai/gpt-5.6
XALGORIX_API_KEY=sk-...
```
Provedor personalizado compatível com OpenAI:
```bash
XALGORIX_LLM=custom/security-model
XALGORIX_API_BASE=https://your-provider.example/v1
XALGORIX_API_KEY=your_provider_api_key
```
#### 🌉 Gateways LiteLLM / compatíveis com OpenAI (GitHub Copilot, Claude Opus, Codex, OpenRouter, Azure, modelos locais)
Como `XALGORIX_API_BASE` aceita qualquer endpoint `/v1/chat/completions` compatível com OpenAI,
o Xalgorix funciona com um proxy [LiteLLM](https://docs.litellm.ai/) imediatamente — sem
necessidade de alterações do lado do Xalgorix. O LiteLLM trata da autenticação do provedor upstream (login de dispositivo do Copilot,
chaves do Azure, OpenRouter, Ollama, etc.); o Xalgorix apenas fala OpenAI com o gateway.
Execute o LiteLLM (exemplo `config.yaml`):
```yaml
model_list:
- model_name: claude-opus-5
litellm_params:
model: github_copilot/claude-opus-5 # or openrouter/…, azure/…, ollama/…
general_settings:
master_key: sk-local-litellm-key
```
Aponte o Xalgorix para ele — use o prefixo `custom/` para que o nome do modelo seja enviado literalmente e o protocolo de chat-completions da OpenAI seja utilizado:
```bash
XALGORIX_LLM=custom/claude-opus-5 # the LiteLLM model_name
XALGORIX_API_BASE=http://localhost:4000/v1 # your LiteLLM proxy
XALGORIX_API_KEY=sk-local-litellm-key # LiteLLM master_key / virtual key
```
O mesmo padrão cobre GitHub Copilot Business/CLI, Claude Opus, modelos no estilo Codex,
OpenRouter, Azure OpenAI e modelos Ollama locais — qualquer coisa que o LiteLLM consiga rotear. Mantenha o
prefixo `custom/` (ou `openai/`) e um `XALGORIX_API_BASE` que não seja Anthropic/Gemini para que o Xalgorix
use o formato de requisição padrão da OpenAI que o LiteLLM espera.
### 🔔 Integrações Opcionais
```bash
GEMINI_API_KEY=AIza...
AGENTMAIL_POD=am_us_pod_47
AGENTMAIL_API_KEY=ak_...
XALGORIX_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
XALGORIX_DISCORD_MIN_SEVERITY=high
```
### 🔐 Autenticação do Dashboard
```bash
XALGORIX_USERNAME=admin
XALGORIX_PASSWORD=change-this-password
```
> [!TIP]
> Prefira `XALGORIX_PASSWORD_HASH` para implantações em produção.
## 🆙 Atualizando de versões anteriores
Esta versão traz uma passagem de estabilidade e isolamento de workspace com uma mudança que quebra compatibilidade e alguns novos ajustes que vale a pena conhecer.
### 💥 Mudança que quebra compatibilidade: workspace padrão movido para `~/.xalgorix/data/`
A saída de varredura, notas, agendamentos e outros artefatos gerados agora ficam em `~/.xalgorix/data/` em vez de `$CWD` (o diretório de onde o binário foi iniciado).
Para manter o comportamento anterior, aponte `XALGORIX_DATA_DIR` para o seu diretório de trabalho atual:
```bash
export XALGORIX_DATA_DIR=$(pwd)
```
Um aviso `[MIGRATION]` é emitido na inicialização quando marcadores legados (`notes.json`, `_schedules/`, `vulnerabilities.json` ou diretórios `YYYY-MM-DD/scan-*`) são detectados em `$CWD` e `XALGORIX_DATA_DIR` não está definido. O Xalgorix nunca lê, copia ou exclui esses arquivos legados automaticamente; o aviso é informativo e só é disparado uma vez por processo.
### 🆕 Nova variável de ambiente
| Variável | Padrão | Descrição |
| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| `XALGORIX_LLM_MAX_INFLIGHT` | `4 × EffectiveMaxInstances` | Limita chamadas LLM de saída simultâneas em todos os scans em execução. Mínimo `1`. Esperas canceladas não consomem um slot. |
### 🩺 Novos contadores do endpoint de saúde
`GET /api/status` agora expõe:
| Campo | Significado |
| --------------------- | ------------------------------------------------------------------------------------ |
| `panics_recovered` | Panics de goroutine, handler HTTP e ferramentas que foram recuperados sem travar. |
| `path_rejections` | Escritas no sistema de arquivos recusadas pelo Path_Policy (fora de `data_dir` / `~/.xalgorix/` / `/tmp`). |
| `watchdog_kills` | Subprocessos encerrados pelo watchdog de timeout rígido por ferramenta. |
| `admission_refusals` | Solicitações de admissão de scan negadas devido ao teto de concorrência. |
| `llm_inflight_cap` | Valor efetivo de `XALGORIX_LLM_MAX_INFLIGHT` para este processo. |
| `data_dir` | Data_Dir resolvido em uso. |
| `allow_list` | Raízes do sistema de arquivos aceitas pelo Path_Policy. |
## 🏃 Executando
### 🪟 Interface Web
```bash
xalgorix --web
```
Abrir:
```text
http://127.0.0.1:9137
```
Use uma porta diferente:
```bash
xalgorix --web --port 8080
```
### 🌐 Acesso Externo
Vincule a outra interface somente após habilitar a autenticação do dashboard:
```bash
XALGORIX_USERNAME=admin XALGORIX_PASSWORD=change-this xalgorix --web --bind 0.0.0.0
```
> [!WARNING]
> O servidor recusa vinculação externa sem autenticação do dashboard.
### 🏹 Varredura CLI
```bash
xalgorix --target https://example.com
```
Com instruções personalizadas:
```bash
xalgorix --target https://app.example.com --instruction "Focus on SQL injection, IDOR, and auth bypass. Avoid destructive tests."
```
## 🧰 Modo de Serviço
Instale e inicie como um serviço de sistema:
```bash
sudo xalgorix --start
```
Gerenciar o serviço:
```bash
sudo xalgorix --restart
sudo xalgorix --stop
sudo xalgorix --uninstall
```
Ver registros:
```bash
journalctl -u xalgorix -f
```
Para descoberta silenciosa ou uma varredura pausada, consulte [diagnosing scan waits](https://github.com/xalgord/xalgorix/blob/main/docs/SCAN_WAITS.md).
### 🌍 Acesso Remoto ao Serviço
Exponha o serviço a navegadores remotos somente após habilitar a autenticação do dashboard:
```bash
sudo tee -a /root/.xalgorix.env >/dev/null <<'EOF'
XALGORIX_BIND=0.0.0.0
XALGORIX_USERNAME=admin
XALGORIX_PASSWORD=change-this
EOF
sudo xalgorix --restart
```
Em seguida, abra `http://<server-ip>:9137`.
Se o processo estiver escutando, mas a página ainda não carregar remotamente, permita a porta TCP `9137` no firewall do servidor ou no grupo de segurança da nuvem.
#### 🏠 Escaneando alvos locais/internos
Por padrão, o Xalgorix se recusa a escanear loopback, `localhost`, faixas de endereços privados ou seus próprios endereços de interface — eles são a máquina onde o Xalgorix é executado, não um alvo. Em uma máquina **auto-hospedada e de locatário único**, você pode optar por escanear um aplicativo de demonstração/staging hospedado localmente:
```bash
echo 'XALGORIX_ALLOW_LOCAL_TARGETS=true' | sudo tee -a /root/.xalgorix.env
sudo xalgorix --restart
```
O próprio listener do dashboard é **sempre** protegido, mesmo com isto ativado.
> **⚠️ Implementações partilhadas / multi-inquilino / alojadas: mantenha isto DESATIVADO.** Ativá-lo
> permitiria que o scan de um utilizador alcançasse a própria máquina do operador e a rede interna.
> Está desativado por predefinição, por isso não é necessária qualquer ação para se manter seguro — não defina
> `XALGORIX_ALLOW_LOCAL_TARGETS` (nem fixe `XALGORIX_ALLOW_LOCAL_TARGETS=false`),
> e não exponha a página Settings do motor a utilizadores não fidedignos.
## 🔁 Fluxo de Trabalho da Web UI
1. Abra o dashboard em `http://127.0.0.1:9137`.
2. Vá a Settings e confirme o fornecedor de LLM, a chave de API, os limites de taxa e as integrações opcionais.
3. Crie um scan a partir de New Scan.
4. Escolha um modo de scan.
5. Selecione as fases da metodologia quando quiser uma execução focada.
6. Defina filtros de severidade quando apenas certas severidades devem ser reportadas em tempo real. O filtro afeta apenas o feed do dashboard em tempo real e as notificações; o relatório PDF e `/api/findings` incluem sempre todas as vulnerabilidades que o agente descobriu.
7. Adicione o nome da empresa e carregue um logótipo para relatórios com a sua marca.
8. Monitorize o progresso a partir de Overview, Scan Detail ou Live Feed.
9. Abra os detalhes dos achados, descarregue relatórios ou faça a gestão de scans históricos a partir de Scans e Reports.
## 🔀 Modos de Scan
| Modo | Melhor para |
| ---------------- | ------------------------------------------------------------------------------- |
| 🎯 Alvo único | Testar um URL ou host conhecido. |
| 🌐 Wildcard / multi | Enumerar alvos relacionados e fazer scan da superfície de ataque descoberta. |
| 🧭 DAST | Testes assistidos por browser para aplicações web, fluxos de autenticação, formulários e comportamento em runtime. |
## 📂 Faça Scan ao Seu Código (sem alvo necessário)
Aponte o Xalgorix a uma base de código — um URL Git, um caminho local ou um zip carregado — e
ele faz scan diretamente ao código-fonte. Sem URL implementado, sem infraestrutura para montar.
```bash
# Source review (SAST): audit the code, no running target required
xalgorix --source ./my-app --code-scan review
# Provision + DAST: build & run the app locally, then pentest the running instance
xalgorix --source https://github.com/org/app.git --code-scan provision
```
| Modo de varredura de código | O que faz | Nível de verificação |
| -------------- | ------------ | ------------------ |
| `review` | Lê o código-fonte, rastreia a entrada do usuário do ponto de entrada → sink perigoso, e reporta vulnerabilidades alcançáveis. Sem alvo ativo. | **Verificado no código-fonte** — comprovadamente alcançável no código (claramente rotulado como não explorado em tempo de execução). |
| `provision` | Inspeciona o repositório, compila e executa a aplicação numa porta de loopback, e depois executa DAST guiado por whitebox contra a instância em execução. Recorre a `review` se a aplicação não puder ser compilada. | **Verificado por exploração** — reproduzido contra a aplicação em execução. |
- `--source` aceita um URL Git (clonado superficialmente), um diretório local, ou um caminho para
um arquivo carregado/extraído. Na Web UI / aplicação hospedada também pode carregar um
`.zip` do seu código-fonte (`POST /api/upload-source`).
- Ainda pode combinar um repositório **e** um alvo ativo para o clássico
aprimoramento whitebox — esse caminho mantém-se inalterado. Os modos de varredura de código são para quando
o código-fonte é o objeto completo.
> O modo provision executa os comandos de compilação/inicialização da sua aplicação na sandbox do agente e
> apenas faz pentest à única porta de loopback onde a aplicação foi levantada — o dashboard
> e tudo o resto na máquina ficam fora do âmbito.
## 🧭 Metodologia
O Xalgorix organiza os testes autónomos em 22 fases.
| Fase | Foco |
| ----: | ------------------------------------------ |
| 1 | Reconhecimento |
| 2 | Descoberta manual de vulnerabilidades |
| 3 | Descoberta de diretórios e ficheiros |
| 4 | Análise de CORS e cookies |
| 5 | Testes de autenticação e sessão |
| 6 | Testes de injeção |
| 7 | Testes de SSRF |
| 8 | IDOR e controlo de acesso quebrado |
| 9 | Testes de API e GraphQL |
| 10 | Testes de upload de ficheiros |
| 11 | Desserialização e RCE |
| 12 | Condições de corrida e lógica de negócio |
| 13 | Subdomain takeover |
| 14 | Testes de open redirect |
| 15 | Testes de segurança de email |
| 16 | Cloud e infraestrutura |
| 17 | Testes de WebSocket |
| 18 | Testes específicos de CMS |
| 19 | Broken link hijacking e content spoofing |
| 20 | Verificação de exploração |
| 21 | Descoberta de vulnerabilidades inéditas |
| 22 | Relatório final |
A seleção de fases na Web UI permite executar todas as fases ou apenas o subconjunto necessário para um envolvimento específico.
## 📄 Relatórios
Os relatórios são gerados como ficheiros PDF e podem incluir:
| Secção | Conteúdo incluído |
| ----------- | ------------------------------------------------------------------------------- |
| 📌 Resumo | Resumo executivo, metadados do alvo, metadados da varredura e visão geral da severidade. |
| 🐞 Achados | Achados verificados, detalhes de CVSS, análise técnica e prova de exploração. |
| 🔬 Evidência | Comandos de prova de conceito, scripts, notas de payload e observações de suporte. |
| 🩹 Remediação | Orientação de correção e próximos passos priorizados. |
| 🎨 Branding | Nome da empresa/alvo e logótipo carregado. |
Os relatórios estão disponíveis na página de detalhe da varredura e na página de Relatórios. As linhas de relatório suportam abertura, download e eliminação.
## 🔧 Configurações
A maioria das configurações operacionais pode ser alterada na Web UI em Configurações.
| Área | Exemplos |
| ------------- | ------------------------------------------------------------------- |
| 🤝 Envolvimento | Limites de taxa de pedidos do dashboard |
| 🧠 LLM | Modelo, chave de API, base de API, esforço de raciocínio, tentativas, iterações máximas |
| 📬 AgentMail | Pod e chave de API |
| 🔔 Notificações | Webhook do Discord e severidade mínima, token do bot do Telegram, ID do chat, severidade mínima, e resumos de conclusão de varredura opt-in |
| 🕵️ Proxy | URL do proxy, ficheiro de proxy, rotação, verificação TLS |
| 🧱 Runtime | Workspace, caminho do browser, controlos de instalação automática |
| 🔐 Segurança | Nome de utilizador do dashboard, palavra-passe, hash da palavra-passe, endereço de bind |
| 📈 Recursos | Limiares de CPU/RAM/disco e orçamento de concorrência de varredura |
Algumas configurações requerem um reinício porque afetam o arranque do processo ou o bind do servidor. A UI marca esses campos.
## 🧾 Variáveis de Ambiente
### 🧱 Core
| Variável | Padrão | Descrição |
| ------------------------------------ | ---------------- | ------------------------------------------------------ |
| `XALGORIX_LLM` | nenhum | ID de modelo nativo do fornecedor usado para pedidos LLM. |
| `XALGORIX_LLM_PROVIDER` | nenhum | Fornecedor selecionado pelo dashboard, armazenado separadamente do ID do modelo. |
| `XALGORIX_API_KEY` | nenhum | Chave de API do fornecedor LLM necessária. |
| `XALGORIX_API_BASE` | padrão do fornecedor | URL base de API compatível com OpenAI personalizada. |
| `XALGORIX_REASONING_EFFORT` | `high` | Esforço de raciocínio: `none`, `low`, `medium`, `high`, ou `xhigh` (`xhigh` mapeia para `high` no Ollama). |
| `XALGORIX_LANGUAGE` | `en` | Idioma de saída para prosa gerada por IA (raciocínio do agente, notas, achados, conteúdo do relatório, chat pós-varredura). `en` ou `zh-CN`. Tokens técnicos (payloads, comandos, URLs, IDs CVE/CWE) mantêm-se sempre na sua forma original. Idiomas não latinos são renderizados no dashboard e no relatório HTML automaticamente. |
| `XALGORIX_PDF_CJK_FONT` | nenhum | Caminho absoluto para uma fonte TrueType (`.ttf`) com glifos CJK, usada para renderizar idiomas não latinos (por exemplo, chinês simplificado) no relatório **PDF** exportado. Apenas `.ttf` é suportado (não `.ttc`/`.otf`). Sem isto, o PDF recorre a fontes base e os glifos não latinos não serão renderizados (o relatório HTML não é afetado). |
| `XALGORIX_OLLAMA_COMPATIBLE` | `false` | Aplicar semântica de raciocínio do Ollama a um endpoint personalizado numa porta não padrão. A porta `11434` é detetada automaticamente. |
| `XALGORIX_LLM_MAX_RETRIES` | `5` | Número de tentativas para falhas transitórias do LLM. |
| `XALGORIX_MEMORY_COMPRESSOR_TIMEOUT` | `30` | Timeout em segundos para compressão de contexto. |
| `XALGORIX_MAX_ITERATIONS` | `0` | Limite de iterações do agente. `0` significa ilimitado. |
| `XALGORIX_PPROF_ADDR` | nenhum | Profiler Go opt-in. Quando definido (por exemplo, `127.0.0.1:6060`), inicia um servidor pprof autónomo em `/debug/pprof/` nesse endereço para diagnóstico de CPU/heap. Desativado por padrão. Expõe os internos do processo — faça bind em loopback e aceda via túnel SSH; nunca exponha publicamente. |
| `GEMINI_API_KEY` | nenhum | Chave Gemini opcional para enriquecimento de pesquisa web. |
### 🔒 Web e Segurança
| Variável | Padrão | Descrição |
| ------------------------ | ----------------- | ---------------------------------- |
| `XALGORIX_BIND` | `127.0.0.1` | Endereço de escuta do servidor web. |
| `XALGORIX_ALLOW_LOCAL_TARGETS` | `false` | Permitir a varredura de aplicações alojadas localmente (localhost / 127.0.0.1 / IPs privados) numa instalação auto-alojada. O próprio listener do dashboard está sempre protegido. Deixe desativado em implementações partilhadas/hospedadas. |
| `XALGORIX_DISABLE_AUTO_DELEGATE` | `false` | Ignorar completamente a vaga de especialistas. O agente raiz faz todos os testes sozinho (mais profundo, mais lento). |
| `XALGORIX_CHECKLIST` | `full` | Profundidade da metodologia: `full` (abrangente de 22 fases, padrão) ou `professional` (compacto). A checklist completa encontra significativamente mais vulnerabilidades. |
| `XALGORIX_USERNAME` | nenhum | Nome de utilizador do dashboard. |
| `XALGORIX_PASSWORD` | nenhum | Palavra-passe do dashboard. |
| `XALGORIX_PASSWORD_HASH` | nenhum | Hash de palavra-passe bcrypt preferido. |
| `XALGORIX_WORKSPACE` | diretório atual | Raiz do workspace para execução de varredura. |
### 🤝 Integrações
| Variável | Padrão | Descrição |
| ------------------------------- | ------- | ---------------------------------------- |
| `AGENTMAIL_POD` | nenhum | Identificador do pod AgentMail. |
| `AGENTMAIL_API_KEY` | nenhum | Chave de API do AgentMail. |
| `XALGORIX_DISCORD_WEBHOOK` | nenhum | Webhook global do Discord. |
| `XALGORIX_DISCORD_MIN_SEVERITY` | nenhum | Severidade mínima enviada para o Discord. |
| `XALGORIX_TELEGRAM_BOT_TOKEN` | nenhum | Token do bot do Telegram do @BotFather. |
| `XALGORIX_TELEGRAM_CHAT_ID` | nenhum | ID do chat/canal do Telegram (numérico ou @username). |
| `XALGORIX_TELEGRAM_MIN_SEVERITY`| nenhum | Severidade mínima enviada para o Telegram. |
| `XALGORIX_NOTIFY_SCAN_COMPLETE` | `false` | Enviar resumos de fim de varredura para destinos Discord/Telegram configurados. Isto é opt-in e não afeta os alertas por vulnerabilidade. |
| `CAIDO_PORT` | `0` | Porta do proxy Caido. `0` significa deteção automática. |
| `CAIDO_API_TOKEN` | nenhum | Token de API do Caido. |
### 🚦 Limites de Taxa, Proxy e Runtime
| Variável | Padrão | Descrição |
| ------------------------------ | ------------ | -------------------------------------------------- |
| `XALGORIX_RATE_LIMIT_REQUESTS` | `60` | Pedidos do dashboard por janela. |
| `XALGORIX_RATE_LIMIT_WINDOW` | `60` | Janela de limite de taxa do dashboard em segundos. |
| `XALGORIX_RATE_RPS` | `10` | Taxa de pedidos de saída sustentada. |
| `XALGORIX_RATE_BURST` | `20` | Tamanho do burst de saída. |
| `XALGORIX_USE_PROXY` | `false` | Ativar encaminhamento por proxy. |
| `XALGORIX_PROXY_REQUIRED` | `false` | Exigir um proxy upstream para caminhos HTTP/browser do alvo sem fallback direto. |
| `XALGORIX_PROXY_URL` | nenhum | URL de proxy único. Substitui o ficheiro de proxy. |
| `XALGORIX_PROXY_FILE` | nenhum | Ficheiro contendo um proxy por linha. |
| `XALGORIX_PROXY_ROTATION` | `roundrobin` | Estratégia de rotação de proxy: `roundrobin` ou `random`. |
| `XALGORIX_TLS_SKIP_VERIFY` | `false` | Ignorar verificação TLS para tráfego de teste. |
| `XALGORIX_DISABLE_BROWSER` | `false` | Desativar automação do browser. |
| `XALGORIX_BROWSER_PATH` | auto | Caminho personalizado do executável Chrome/Chromium. |
| `XALGORIX_ALLOW_AUTO_INSTALL` | apenas root | Permitir instalação automática de pacotes. |
| `XALGORIX_AUTO_INSTALL_SUDO` | `false` | Permitir instalações automáticas com prefixo sudo. |
## 🔤 Prefixos de Fornecedor
Quando `XALGORIX_API_BASE` está vazio, o Xalgorix infere os padrões do fornecedor a partir do prefixo do modelo.
| Prefixo | Base de API padrão |
| ------------ | ---------------------------------------------- |
| `openai/` | `https://api.openai.com/v1` |
| `anthropic/` | `https://api.anthropic.com` |
| `deepseek/` | `https://api.deepseek.com/v1` |
| `groq/` | `https://api.groq.com/openai/v1` |
| `google/` | `https://generativelanguage.googleapis.com/v1` |
| `gemini/` | `https://generativelanguage.googleapis.com/v1` |
| `ollama/` | `http://localhost:11434/v1` |
| `minimax/` | `https://api.minimax.io/v1` |
Os nomes dos modelos não estão codificados nesta lista. A página de Configurações aceita IDs de modelo digitados para que modelos mais recentes dos fornecedores possam ser usados sem esperar por uma atualização do dropdown da UI.
## 💻 Referência da CLI
| Flag | Alias | Descrição |
| ---------------------- | ----- | ------------------------------------------ |
| `--web` | `-w` | Iniciar a Web UI. |
| `--port <port>` | `-p` | Porta da Web UI. Padrão: `9137`. |
| `--bind <addr>` | nenhum | Endereço de bind. Padrão: `127.0.0.1`. |
| `--target <target>` | `-t` | URL, host, IP ou caminho do alvo. Repetível. |
| `--instruction <text>` | `-i` | Instruções de varredura personalizadas. |
| `--model <model>` | `-m` | Substituir `XALGORIX_LLM` para esta execução. |
| `--update` | `-up` | Atualizar para a versão mais recente. |
| `--version` | `-v` | Imprimir versão. |
| `--start` | nenhum | Instalar e iniciar o serviço de sistema. |
| `--stop` | nenhum | Parar o serviço de sistema. |
| `--restart` | nenhum | Reiniciar o serviço de sistema. |
| `--uninstall` | nenhum | Remover o serviço de sistema. |
| `--help` | `-h` | Mostrar ajuda. |
## 📡 Resumo da API
| Método | Endpoint | Propósito |
| -------- | ---------------------------- | --------------------------------------------- |
| `POST` | `/api/scan` | Iniciar ou guardar uma varredura. |
| `POST` | `/api/stop` | Parar todas as varreduras em execução. |
| `GET` | `/api/status` | Estado global atual. |
| `GET` | `/api/scans` | Listar varreduras. |
| `GET` | `/api/scans/:id` | Obter detalhe da varredura. |
| `DELETE` | `/api/scans/:id` | Eliminar uma varredura e os seus dados de relatório. |
| `GET` | `/api/findings` | Listar todos os achados (deduplicados entre varreduras). |
| `GET` | `/api/findings/summary` | Contagem de severidade em todas as varreduras. |
| `GET` | `/api/report/:id` | Descarregar um relatório PDF. |
| `GET` | `/api/instances` | Listar instâncias ativas e históricas. |
| `GET` | `/api/instances/:id/events` | Obter histórico de eventos em buffer. |
| `POST` | `/api/instances/:id/stop` | Parar uma instância específica. |
| `POST` | `/api/instances/:id/start` | Iniciar uma varredura guardada ou concluída como uma nova execução. |
| `POST` | `/api/instances/:id/restart` | Reiniciar com a mesma configuração. |
| `POST` | `/api/instances/:id/pause` | Pausar uma varredura em execução. |
| `POST` | `/api/instances/:id/resume` | Retomar uma varredura em pausa. |
| `POST` | `/api/upload-logo` | Carregar um logótipo de relatório. |
| `POST` | `/api/upload-targets` | Carregar uma lista de alvos. |
| `GET` | `/api/settings/environment` | Listar configurações de ambiente editáveis. |
| `POST` | `/api/settings/environment` | Guardar configurações de ambiente. |
| `GET` | `/api/settings/llm` | Obter configurações do LLM. |
| `POST` | `/api/settings/llm` | Guardar configurações do LLM. |
| `GET` | `/api/settings/agentmail` | Obter configurações do AgentMail. |
| `POST` | `/api/settings/agentmail` | Guardar configurações do AgentMail. |
| `GET` | `/ws` | Stream de eventos ao vivo via WebSocket. |
## 💾 Armazenamento de Dados
Os dados de varredura em modo web são armazenados em:
```text
~/xalgorix-data/
|-- _saved/
|-- logos/
|-- queue_state.json
`-- <target>/
`-- <date>/
`-- <scan-id>/
|-- scan.json
`-- report.pdf
```
O servidor mantém registros históricos de varredura em disco para que a UI possa se recuperar após atualização ou reinicialização.
Na imagem Docker e no Helm chart, este diretório é o volume `/data` (`XALGORIX_DATA_DIR=/data`), persistido em um volume nomeado ou um PVC.
## 🧪 Desenvolvimento
| Tarefa | Comando |
| --------------------------- | ----------------------------- |
| 📦 Instalar dependências da Web UI | `make webui-install` |
| 🔨 Compilar tudo | `make build` |
| ✅ Executar testes | `go test ./...` |
| 🖥️ Executar Web UI a partir do código-fonte | `go run ./cmd/xalgorix --web` |
| ⚡ Executar servidor de desenvolvimento do frontend | `make webui-dev` |
## 🚨 Notas de Segurança
- Use o Xalgorix apenas contra alvos autorizados.
- Não execute testes ativos contra sistemas de terceiros sem permissão.
- Revise as instruções de varredura antes de iniciar.
- Configure limites de taxa e configurações de proxy para corresponder às regras do engajamento.
- Expor o dashboard externamente requer autenticação.
- A instalação automática está desabilitada por padrão para usuários não-root e deve ser habilitada apenas quando você confiar no ambiente.
## 📜 Licença
Xalgorix é distribuído sob a Apache License 2.0. Consulte [LICENSE](https://github.com/xalgord/xalgorix/blob/main/LICENSE).
## 🔗 Links
| Recurso | Link |
| ------------- | -------------------------------------------------------------------------------- |
| ☁️ Hospedado (Cloud) | [www.xalgorix.com](https://www.xalgorix.com/) |
| 📖 Documentação | [docs.xalgorix.com](https://docs.xalgorix.com) |
| 🐛 Issues | [github.com/xalgorix/xalgorix/issues](https://github.com/xalgorix/xalgorix/issues) |
| ☕ Suporte | [buymeacoffee.com/xalgord](https://buymeacoffee.com/xalgord) |