Autonoma

Autonoma detecta segredos codificados e os substitui por referências os.environ[...] usando reescritas de AST. As alterações são aplicadas apenas quando a reescrita é determinística e preserva a semântica.

As reescritas usam a árvore sintática analisada — não regex em texto bruto.
Executa localmente sem chamadas de rede. Funciona em CI com diffs idempotentes e mínimos.

---

Que problema isso resolve

Segredos codificados em bases de código:

• segredos são commitados e permanecem no histórico do git
• corrigi-los manualmente quebra o código ou perde casos limite
• equipes detectam vazamentos mas evitam ferramentas de correção automática porque são inseguras

A maioria das ferramentas os detecta.
Autonoma só mexe no que consegue provar que é seguro alterar.

---

Exemplo rápido

autonoma scan .
autonoma fix .
git diff

Instalação

pip install autonoma-cli

Integração com Pre-commit

Adicione isto ao seu .pre-commit-config.yaml para impedir que segredos entrem no histórico:

- repo: local
  hooks:
    - id: autonoma
      name: Autonoma Scan
      entry: autonoma scan
      language: system
      types: [python]

---

Experimente em 60 segundos

# 1. Crie um arquivo de teste com segredos codificados
cat > test_secrets.py << 'EOF'
SENDGRID_API_KEY = "sg-live-abc123xyz789"
DB_PASSWORD = "Pr0dAccess2024!"
EOF

# Crie também o arquivo de contrato de ambiente (necessário para remediação segura)
printf 'SENDGRID_API_KEY=\nDB_PASSWORD=\n' > .env.example

# 2. Escaneie — emite resultados JSON para stdout
autonoma scan test_secrets.py

# 3. Corrija — reescreve o arquivo no lugar
autonoma fix test_secrets.py

# 4. Escaneie novamente — agora deve estar limpo (código de saída 0)
autonoma scan test_secrets.py

# 5. Inspecione o resultado
cat test_secrets.py

Saída esperada após a correção:

import os
SENDGRID_API_KEY = os.environ["SENDGRID_API_KEY"]
DB_PASSWORD = os.environ["DB_PASSWORD"]

---

Comandos

scan

Modo de detecção. Envia JSON para stdout e um resumo legível para stderr. Não mutante — nunca modifica arquivos.

# Escaneie um diretório (resultados JSON para stdout)
autonoma scan src/

# Salve resultados JSON em um arquivo
autonoma scan src/ > findings.json

Códigos de saída para scan:

Código	Significado
0	Nenhuma ocorrência
1	Ocorrências detectadas
3	Erro da ferramenta

fix

Remedia segredos codificados usando reescritas de AST. Modifica arquivos no lugar.

# Aplique correções
autonoma fix src/

# Visualize as alterações antes de escrever
autonoma fix src/ --diff

# Escreva um registro de auditoria da remediação
autonoma fix src/ --report-out audit.json

Códigos de saída para fix:

Código	Significado
0	Nenhuma ocorrência — repositório já estava limpo
1	Ocorrências existiam antes da remediação (a remediação pode ter sido bem-sucedida — verifique a saída para contagens de CORRIGIDO/RECUSADO)
3	Erro da ferramenta

O comando fix sai com código 1 sempre que encontra segredos antes de tentar a remediação, independentemente de a reescrita ter sido bem-sucedida. Isso é intencional: pipelines de CI devem sinalizar o commit onde os segredos foram introduzidos, mesmo após a correção automática. Execute autonoma scan depois para confirmar que o repositório está limpo.

history-scan

Escaneia o histórico do git em busca de segredos que foram commitados e depois removidos ou alterados.

[!NOTE] Apenas detecção. Este comando não reescreve o histórico do git nem modifica commits.

autonoma history-scan .

---

Antes / Depois

Estes são os padrões que a Autonoma corrige atualmente.

Antes

# settings.py
SENDGRID_API_KEY = "sg-live-abc123xyz789"
DB_PASSWORD = "Pr0dAccess2024!"

Depois (autonoma fix .)

# settings.py
import os
SENDGRID_API_KEY = os.environ["SENDGRID_API_KEY"]
DB_PASSWORD = os.environ["DB_PASSWORD"]

Recusado (segurança de recusa primeiro)

# f-string — recusado porque a reescrita mudaria a semântica
api_key = f"prefix_{BASE_KEY}"
# → RECUSADO: refuse_fstring_mixed_expression

# Valor aninhado em dicionário — recusado porque o alvo não é uma atribuição simples
DATABASES = {
    "default": {"PASSWORD": "Pr0d@ccess2024!"}
}
# → RECUSADO: tipo de alvo de atribuição não suportado

Ocorrências recusadas são relatadas na saída JSON e causam um código de saída diferente de zero no CI. Arquivos com ocorrências recusadas nunca são modificados.

---

O que a Autonoma corrige vs recusa

Padrão	Exemplo	Comportamento	Porquê
Atribuição simples	api_key = "sk-abc123"	Corrigido	Reescrita determinística de AST
Atributo de classe	class C: SECRET = "abc"	Corrigido	Reescrita determinística de AST
Argumento nomeado	connect(password="abc")	Corrigido	Reescrita determinística de AST
f-string	key = f"prefix_{v}"	Recusado	A reescrita alteraria o comportamento em tempo de execução
Concatenação	key = "sk-" + suffix	Recusado	A reescrita alteraria o comportamento em tempo de execução
Valor aninhado em dicionário	cfg = {"pass": "abc"}	Recusado	Não é um alvo de atribuição simples
Atribuição múltipla	A = B = "secret"	Recusado	Alvo ambíguo
Já seguro	key = os.getenv("KEY")	Ignorado	Nenhuma alteração necessária
.env.example ausente	qualquer padrão	Recusado	Nenhum contrato de ambiente para derivar o nome da variável

---

Funcionalidades de CI/CD

Reexecutar em um arquivo limpo não faz alterações. As reescritas mantêm a indentação original e os comentários. import os é adicionado apenas se estiver ausente.

Integração e CI/CD

GitHub Actions (Apenas Escaneamento)

Para falhar a build se qualquer segredo for detectado:

- name: Scan for secrets
  run: autonoma scan .

---

Comandos Legados

analyze é mantido para compatibilidade retroativa. Migre para scan ou fix.

# Equivalente a 'autonoma scan'
autonoma analyze src/ --detect-only

# Equivalente a 'autonoma fix'
autonoma analyze src/ --auto-fix

---

Restrições e Comportamentos

O que ele remedia

• Atribuições simples: API_KEY = "secret"
• Atributos de classe: class Config: PASS = "secret"
• Argumentos nomeados: connect(password="secret")

O que ele recusa (por design)

• Expressões Complexas: f-strings, concatenações ou chamadas de função no lado direito.
• Alvos Ambíguos: Atribuições múltiplas (A = B = "secret") ou desempacotamento de tuplas.
• Valores Aninhados/em Dicionários: Valores dentro de dicionários, listas ou tuplas.
• Contexto Ausente: Se nenhum .env.example ou contrato de ambiente for encontrado no repositório.

Casos recusados são relatados na saída JSON e causarão códigos de saída diferentes de zero no CI. O arquivo nunca é modificado se qualquer problema nele for recusado.

O que ele não faz

• Não usa entropia/adivinhação (usa correspondência heurística de nomes).
• Não modifica arquivos que não são Python na Edição Community.
• Não exclui seu código; backups são escritos como <arquivo>.bak antes da modificação.

---

Limitações atuais