Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Política de segurança

Versões com suporte

Só a linha menor mais recente recebe correções de segurança. Atualize para a linha menor atual antes de relatar uma vulnerabilidade contra uma linha mais antiga.

Como relatar uma vulnerabilidade

Levamos a segurança a sério. Se você descobrir uma vulnerabilidade, relate-a com responsabilidade:

1. Contato privado: use o canal de contato da AutomatosX para pedir uma rota confidencial de relato de segurança. Não inclua detalhes de exploração nem credenciais em mensagens públicas da comunidade.
2. Discord: relate no nosso Discord: https://discord.gg/gf9UyPxaN2

Vamos acusar o recebimento do relato em até 6 dias úteis e manter você informado do avanço até uma correção.

Nota: não aceitamos relatos de segurança gerados por IA. Enviar um resulta em banimento do projeto. Garanta que o relato inclua passos específicos de reprodução e demonstre um impacto real.

Modelo de ameaça

Visão geral

O ax-code é um assistente de programação com IA que executa localmente na sua máquina. Ele oferece um sistema de agente com acesso a ferramentas potentes, inclusive execução de shell, operações de arquivo e acesso à web.

O padrão de isolamento do runtime é full-access (sandbox desligado), com gravações no sistema de arquivos e acesso à rede sem restrição. Esta é uma postura de conveniência para projetos locais confiáveis, não uma fronteira de segurança. Selecione workspace-write ou read-only antes de usar o AX Code com repositórios não confiáveis ou cargas sem supervisão.

Sandbox de isolamento de execução

O ax-code inclui um sandbox embutido de isolamento de execução que restringe o que o agente de IA pode acessar. Há três modos:

Propriedades principais:

• Comportamento padrão — o AX Code inicia em full-access, a menos que --sandbox, AX_CODE_ISOLATION_MODE ou a configuração definam outro modo
• Modo restrito recomendado — use workspace-write para repositórios não confiáveis ou de equipe; ele confina as gravações ao workspace e desativa a rede por padrão
• Imposição no nível da ferramenta — todas as ferramentas de mutação (bash, edit, write, apply_patch) e as ferramentas de rede (webfetch, websearch, codesearch) conferem a política de isolamento antes de executar
• Caminhos protegidos — os diretórios .git e .ax-code ficam sempre protegidos contra gravação, mesmo no modo de gravação no workspace
• Prompts de elevação — nos modos restritos, violações de isolamento apresentam um diálogo de aprovação em vez de falhar em silêncio; o usuário pode permitir uma operação bloqueada uma vez, sem mudar a configuração
• Controle pela CLI — --sandbox read-only, --sandbox workspace-write, --sandbox full-access
• Variável de ambiente — AX_CODE_ISOLATION_MODE

Backends de isolamento

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

Ou defina AX_CODE_ISOLATION_BACKEND=os|auto|app.

O isolamento do sistema para o bash nega gravações fora das raízes do workspace e nega a rede quando network: false. As checagens da camada da aplicação ainda executam sempre. Em plataformas sem Seatbelt ou bubblewrap, use backend: "app" ou um contêiner ou máquina virtual.

Segurança do servidor

• Somente localhost por padrão — o servidor se vincula a 127.0.0.1, inacessível a partir da rede
• Senha exigida para acesso pela rede — vincular a 0.0.0.0 ou a qualquer endereço que não seja localhost exige que AX_CODE_SERVER_PASSWORD esteja definido; o servidor recusa iniciar sem isso
• Autenticação básica imposta — quando AX_CODE_SERVER_PASSWORD está definido, HTTP Basic Auth é exigido em todos os endpoints da API
• CORS configurável — origens adicionais permitidas podem ser especificadas por --cors

Armazenamento de credenciais

As chaves de API dos provedores são criptografadas em repouso com AES-256-GCM e derivação de chave PBKDF2, e armazenadas no diretório local de dados do AX Code (~/.local/share/ax-code/) com permissões de arquivo só do usuário (0600).

A chave de criptografia é derivada de atributos da máquina local (nome do host, plataforma, arquitetura). Isso protege contra divulgação casual offline (por exemplo, compartilhamento acidental de arquivo), mas não protege contra um atacante determinado com acesso ao host. Não equivale a um chaveiro do sistema nem a armazenamento de segredo apoiado em hardware.

Tokens OAuth de MCP, segredos de cliente e tokens de acesso e de atualização de conta também são criptografados em repouso pelo mesmo mecanismo. Metadados não sensíveis (URLs de servidor, marcas de expiração, e-mail, IDs de conta) permanecem em texto claro.

Verificação de artefatos de versão

Tanto o instalador Bash (install) quanto o instalador PowerShell do Windows (install.ps1) verificam os arquivos baixados de versão do GitHub com Minisign antes da extração. Os arquivos de versão e o próprio script do instalador PowerShell carregam assinaturas destacadas. A chave pública fixada de versão do AX Code é:

RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO

Cada instalador baixa o ativo correspondente .minisig do arquivo selecionado e falha fechado quando a verificação falha. Se minisign ainda não estiver no PATH, os instaladores baixam os arquivos oficiais fixados do Minisign 0.12 a partir de https://download.ax-code.com/vendor/minisign/0.12/, conferem o SHA-256 do arquivo e conferem de novo o executável extraído antes de guardá-lo em cache. Um binário minisign que já esteja no PATH é a ferramenta do operador e não é reprocessado por hash. Defina AX_CODE_SKIP_MINISIGN_VERIFY=1 somente quando você aceitar de propósito um download de versão que não se pode verificar.

O atalho de uma linha irm …/install.ps1 | iex não verifica o script do instalador antes da execução. Para instalações sensíveis à segurança, baixe install.ps1 e install.ps1.minisig, verifique o script com Minisign e depois execute-o localmente (veja Canais de instalação e de runtime).

Quem mantém deve guardar a chave secreta do Minisign criptografada. Para assinar versões localmente no macOS, guarde a frase secreta no Keychain, em vez de num arquivo em texto claro:

security add-generic-password -U -a ax-release -s ax-minisign -w

A ferramenta de versão lê esse item do Keychain de forma automática quando AX_CODE_MINISIGN_PASSWORD não está definido.

O fluxo de versão do GitHub, disparado pela tag, assina os arquivos antes do envio. Ele exige estes segredos do repositório:

AX_CODE_MINISIGN_SECRET_KEY_B64
AX_CODE_MINISIGN_PASSWORD

AX_CODE_MINISIGN_SECRET_KEY_B64 precisa ser o conteúdo, codificado em base64, da chave secreta criptografada do Minisign ax.minisign.key (o caminho local pode ser um link simbólico para ax.sec). O fluxo grava isso num arquivo temporário de chave 0600, verifica a chave pública fixada, assina cada arquivo de versão e envia os ativos correspondentes .minisig junto dos arquivos.

Para arquivos da CLI no macOS, o fluxo exige e importa o certificado Apple Developer ID usando estes segredos do repositório:

APPLE_CERTIFICATE
APPLE_CERTIFICATE_PASSWORD
APPLE_TEAM_ID
APPLE_API_KEY_B64
APPLE_API_KEY_ID
APPLE_API_ISSUER

Nesse caminho, as bibliotecas nativas empacotadas são assinadas com a identidade importada Developer ID Application, o ZIP do macOS é enviado ao serviço de notarização da Apple, e o ZIP inalterado é então protegido pela assinatura destacada do Minisign. Arquivos ZIP não podem receber o grampo, então a notarização precisa acontecer antes do envio do artefato e antes da geração de .minisig. As compilações de versão falham fechadas quando falta qualquer credencial de assinatura ou de notarização da Apple.

Histórico da chave de assinatura de versão

A chave de assinatura de versão foi substituída pela última vez em 2026-07-19. O instalador e o fluxo de versão fixam só a chave atual, então arquivos assinados com uma chave aposentada falham na verificação da assinatura. Depois de uma substituição, quem mantém precisa reassinar os arquivos históricos de versão com script/resign-release-assets.ts, para que cada versão publicada verifique contra a chave fixada sem confiar em chaves aposentadas.

Para reassinar e reenviar os ativos .minisig de uma versão existente com a chave atual:

tsx script/resign-release-assets.ts --tag v5.5.0 --key-dir ~/signkey

Escopo

Dentro do escopo

Fora do escopo

Capacidades de segurança empresarial

O AX Code é desenhado para uso empresarial, com os seguintes recursos de endurecimento:

• Permissões de grão fino: conjuntos de regras específicos do agente e baseados em padrão (allow/deny/ask). O agente de segurança começa somente leitura. As regras são avaliadas entre projeto, agente e listas aprovadas.
• Trilhas de auditoria da sessão: cada chamada de ferramenta, decisão de permissão e alteração de arquivo é registrada em SQLite, com instantâneos. Aceita reprodução, bifurcação e exportação para revisões de conformidade.
• Refatoração determinística (DRE): impact_analyze, refactor_plan e refactor_apply (worktree sombra mais lint, verificação de tipos e testes) oferecem alterações auditáveis e reversíveis.
• Gestão de credenciais: criptografia AES-256-GCM para todas as chaves e tokens. Isolamento por diretório por InstanceState.
• Imposição opcional de sandbox: isolamento no nível da aplicação, com análise de comando bash (tree-sitter). Selecione workspace-write ou read-only para impor as fronteiras do sandbox; caminhos protegidos (.git, .ax-code) valem nos modos com sandbox.
• Endurecimento do servidor: somente localhost por padrão; acesso remoto protegido por senha, com Basic Auth.
• Inteligência e varredura de código: detecção embutida de segredo e de valor fixo no código, e análise de impacto de dependência.

Retorno de código assistido por CodeQL

O repositório executa o CodeQL como uma camada de análise de segurança em segundo plano para pull requests, envios para dev, varreduras agendadas e disparos manuais. O CodeQL não faz parte do caminho ao vivo de LSP nem de inteligência de código; é uma fonte de evidência mais lenta e mais profunda para achados de fluxo de dados, de contaminação e de qualidade de segurança, que são melhor tratados depois que as alterações de código-fonte se estabilizaram.

O fluxo atual analisa:

• Código de runtime, TUI, SDK, integração e scripts em JavaScript e TypeScript.
• Fluxos do GitHub Actions e ações compostas locais.
• Crates Rust em crates/, com uma compilação Cargo manual, para que o código de complemento nativo e da TUI seja extraído de forma consistente.

A experiência pretendida de quem desenvolve é:

1. Autores de PR recebem alertas do CodeQL na varredura de código do GitHub, junto da verificação de tipos já existente, dos testes determinísticos, da varredura de dependências OSV e das proteções de estrutura do repositório.
2. Quem mantém faz a triagem dos resultados iniciais antes de tratar o CodeQL como uma barreira rígida de merge, para que achados novos sejam úteis em vez de ruidosos.
3. Fluxos futuros de revisão e de depuração do AX Code podem ingerir SARIF do CodeQL ou alertas de varredura de código do GitHub como evidência explícita de segurança, com campos de proveniência como source: "codeql", id da regra, severidade, arquivo, linha, rastreio de fluxo de dados e SHA do commit analisado.
4. A evidência do CodeQL deve ser mostrada ao lado de security_scan local, hardcode_scan, diagnósticos de LSP e análise de impacto apoiada em grafo, e não como uma substituição oculta de qualquer um deles.

Ao acrescentar consultas personalizadas de CodeQL, prefira fronteiras de segurança específicas do repositório a checagens amplas no estilo de lint. Alvos de alto valor incluem caminhos de fuga do sandbox, execução de comando com argumentos não sanitizados, travessia de caminho em torno da contenção do workspace, propagação de segredo ou de ambiente para processos filhos e validação ausente de rota do servidor.

Para governança empresarial completa (RBAC, política como código, exportação para SIEM, auditoria criptográfica), integre com o AX Trust (item de roteiro).

Veja docs/guides/sandbox.md para a configuração de isolamento e o comportamento em runtime.