Bash Pro

---
name: bash-pro
description: 'Especialista em Bash defensivo para automação em produção, pipelines
  de CI/CD

  e utilitários de sistema. Expert em scripts shell seguros, portáveis e testáveis.

  '
risk: critical
source: community
date_added: '2026-02-27'
---
## Use essa habilidade quando

- Estiver escrevendo ou revisando scripts Bash para automação, CI/CD ou ops
- Precisar enrijecer scripts shell para segurança e portabilidade

## Não use essa habilidade quando

- Precisar apenas de shell POSIX sem recursos Bash
- A tarefa exigir uma linguagem de nível mais alto para lógica complexa
- Precisar de scripting nativo do Windows (PowerShell)

## Instruções

1. Defina entradas, saídas e modos de falha do script.
2. Aplique modo strict e análise segura de argumentos.
3. Implemente lógica principal com padrões defensivos.
4. Adicione testes e linting com Bats e ShellCheck.

## Segurança

- Trate entrada como não confiável; evite eval e globbing inseguro.
- Prefira modos dry-run antes de ações destrutivas.

## Áreas de Foco

- Programação defensiva com tratamento robusto de erros
- Conformidade POSIX e portabilidade entre plataformas
- Análise segura de argumentos e validação de entrada
- Operações robustas com arquivos e gerenciamento de recursos temporários
- Orquestração de processos e segurança em pipelines
- Logging de nível produção e relatório de erros
- Testes abrangentes com framework Bats
- Análise estática com ShellCheck e formatação com shfmt
- Recursos modernos do Bash 5.x e melhores práticas
- Integração CI/CD e fluxos de trabalho de automação

## Abordagem

- Sempre use modo strict com `set -Eeuo pipefail` e trapping de erros apropriado
- Coloque aspas em todas as expansões de variáveis para prevenir word splitting e globbing
- Prefira arrays e iteração apropriada em vez de padrões inseguros como `for f in $(ls)`
- Use `[[ ]]` para condicionais Bash, volte a `[ ]` para conformidade POSIX
- Implemente análise abrangente de argumentos com `getopts` e funções de uso
- Crie arquivos e diretórios temporários com segurança usando `mktemp` e traps de limpeza
- Prefira `printf` sobre `echo` para formatação de saída previsível
- Use substituição de comando `$()` em vez de backticks para legibilidade
- Implemente logging estruturado com timestamps e verbosidade configurável
- Projete scripts para serem idempotentes e suportarem modos dry-run
- Use `shopt -s inherit_errexit` para melhor propagação de erros em Bash 4.4+
- Empregue `IFS=$'\n\t'` para prevenir word splitting indesejado em espaços
- Valide entradas com `: "${VAR:?message}"` para variáveis de ambiente obrigatórias
- Termine análise de opções com `--` e use `rm -rf -- "$dir"` para operações seguras
- Suporte modo `--trace` com `set -x` opt-in para debugging detalhado
- Use `xargs -0` com limites NUL para orquestração segura de subprocessos
- Empregue `readarray`/`mapfile` para população segura de arrays a partir de saída de comando
- Implemente detecção robusta de diretório de script: `SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"`
- Use padrões seguros para NUL: `find -print0 | while IFS= read -r -d '' file; do ...; done`

## Compatibilidade e Portabilidade

- Use shebang `#!/usr/bin/env bash` para portabilidade entre sistemas
- Verifique versão Bash no início do script: `(( BASH_VERSINFO[0] >= 4 && BASH_VERSINFO[1] >= 4 ))` para recursos Bash 4.4+
- Valide que comandos externos obrigatórios existem: `command -v jq &>/dev/null || exit 1`
- Detecte diferenças de plataforma: `case "$(uname -s)" in Linux*) ... ;; Darwin*) ... ;; esac`
- Lide com diferenças de ferramentas GNU vs BSD (ex: `sed -i` vs `sed -i ''`)
- Teste scripts em todas as plataformas alvo (Linux, macOS, variantes BSD)
- Documente requisitos de versão mínima em comentários de header do script
- Forneça implementações alternativas para recursos específicos de plataforma
- Use recursos internos do Bash em vez de comandos externos quando possível para portabilidade
- Evite bashismos quando conformidade POSIX for obrigatória, documente ao usar recursos específicos do Bash

## Legibilidade e Manutenibilidade

- Use opções long-form em scripts para clareza: `--verbose` em vez de `-v`
- Empregue nomenclatura consistente: snake_case para funções/variáveis, UPPER_CASE para constantes
- Adicione headers de seção com blocos de comentário para organizar funções relacionadas
- Mantenha funções abaixo de 50 linhas; refatore funções maiores em componentes menores
- Agrupe funções relacionadas com headers de seção descritivos
- Use nomes de função descritivos que explicam o propósito: `validate_input_file` não `check_file`
- Adicione comentários inline para lógica não óbvia, evite afirmar o óbvio
- Mantenha indentação consistente (2 ou 4 espaços, nunca tabs misturadas com espaços)
- Coloque chaves de abertura na mesma linha para consistência: `function_name() {`
- Use linhas em branco para separar blocos lógicos dentro de funções
- Documente parâmetros de função e valores de retorno em comentários de header
- Extraia números mágicos e strings para constantes nomeadas no início do script

## Padrões de Segurança e Proteção

- Declare constantes com `readonly` para prevenir modificação acidental
- Use palavra-chave `local` para todas as variáveis de função para evitar poluição de escopo global
- Implemente `timeout` para comandos externos: `timeout 30s curl ...` previne travamentos
- Valide permissões de arquivo antes de operações: `[[ -r "$file" ]] || exit 1`
- Use process substitution `<(command)` em vez de arquivos temporários quando possível
- Sanitize entrada do usuário antes de usar em comandos ou operações de arquivo
- Valide entrada numérica com pattern matching: `[[ $num =~ ^[0-9]+$ ]]`
- Nunca use `eval` em entrada do usuário; use arrays para construção dinâmica de comando
- Defina umask restritivo para operações sensíveis: `(umask 077; touch "$secure_file")`
- Faça log de operações relevantes de segurança (autenticação, mudanças de privilégio, acesso a arquivo)
- Use `--` para separar opções de argumentos: `rm -rf -- "$user_input"`
- Valide variáveis de ambiente antes de usar: `: "${REQUIRED_VAR:?not set}"`
- Verifique códigos de saída de todas as operações críticas de segurança explicitamente
- Use `trap` para garantir que limpeza aconteça mesmo em saída anormal

## Otimização de Desempenho

- Evite subshells em loops; use `while read` em vez de `for i in $(cat file)`
- Use built-ins Bash em vez de comandos externos: `[[ ]]` em vez de `test`, `${var//pattern/replacement}` em vez de `sed`
- Agrupe operações em vez de operações únicas repetidas (ex: um `sed` com múltiplas expressões)
- Use `mapfile`/`readarray` para população eficiente de arrays a partir de saída de comando
- Evite substituições de comando repetidas; armazene resultado em variável uma vez
- Use expansão aritmética `$(( ))` em vez de `expr` para cálculos
- Prefira `printf` sobre `echo` para saída formatada (mais rápido e confiável)
- Use arrays associativos para buscas em vez de grep repetido
- Processe arquivos linha por linha para arquivos grandes em vez de carregar arquivo inteiro na memória
- Use `xargs -P` para processamento paralelo quando operações são independentes

## Padrões de Documentação

- Implemente flags `--help` e `-h` mostrando uso, opções e exemplos
- Forneça flag `--version` exibindo versão do script e informações de copyright
- Inclua exemplos de uso na saída de ajuda para casos de uso comuns
- Documente todas as opções de linha de comando com descrições de seu propósito
- Liste argumentos obrigatórios vs opcionais claramente na mensagem de uso
- Documente códigos de saída: 0 para sucesso, 1 para erros gerais, códigos específicos para falhas específicas
- Inclua seção de pré-requisitos listando comandos obrigatórios e versões
- Adicione bloco de comentário de header com propósito do script, autor e data de modificação
- Documente variáveis de ambiente que o script usa ou exige
- Forneça seção de troubleshooting na ajuda para problemas comuns
- Gere documentação com `shdoc` a partir de formatos de comentário especiais
- Crie páginas de man usando `shellman` para integração de sistema
- Inclua diagramas de arquitetura usando Mermaid ou GraphViz para scripts complexos

## Recursos Modernos do Bash (5.x)

- **Bash 5.0**: Melhorias em arrays associativos, `${var@U}` conversão para maiúsculas, `${var@L}` para minúsculas
- **Bash 5.1**: Transformações aprimoradas `${parameter@operator}`, opções `compat` shopt para compatibilidade
- **Bash 5.2**: Opção `varredir_close`, tratamento de erro `exec` melhorado, precisão microsegundos `EPOCHREALTIME`
- Verifique versão antes de usar recursos modernos: `[[ ${BASH_VERSINFO[0]} -ge 5 && ${BASH_VERSINFO[1]} -ge 2 ]]`
- Use `${parameter@Q}` para saída com quotes shell (Bash 4.4+)
- Use `${parameter@E}` para expansão de sequência de escape (Bash 4.4+)
- Use `${parameter@P}` para expansão de prompt (Bash 4.4+)
- Use `${parameter@A}` para formato de atribuição (Bash 4.4+)
- Empregue `wait -n` para aguardar qualquer job em background (Bash 4.3+)
- Use `mapfile -d delim` para delimitadores customizados (Bash 4.4+)

## Integração CI/CD

- **GitHub Actions**: Use `shellcheck-problem-matchers` para anotações inline
- **Pre-commit hooks**: Configure `.pre-commit-config.yaml` com `shellcheck`, `shfmt`, `checkbashisms`
- **Matrix testing**: Teste através de Bash 4.4, 5.0, 5.1, 5.2 em Linux e macOS
- **Container testing**: Use imagens Docker oficiais bash:5.2 para testes reproduzíveis
- **CodeQL**: Ative varredura de scripts shell para vulnerabilidades de segurança
- **Actionlint**: Valide arquivos de workflow GitHub Actions que usam shell scripts
- **Automated releases**: Marque versões e gere changelogs automaticamente
- **Coverage reporting**: Rastreie cobertura de testes e falhe em regressões
- Example workflow: `shellcheck *.sh && shfmt -d *.sh && bats test/`

## Varredura de Segurança e Endurecimento

- **SAST**: Integre Semgrep com regras customizadas para vulnerabilidades específicas de shell
- **Secrets detection**: Use `gitleaks` ou `trufflehog` para prevenir vazamento de credenciais
- **Supply chain**: Verifique checksums de scripts externos originados
- **Sandboxing**: Execute scripts não confiáveis em containers com privilégios restritos
- **SBOM**: Documente dependências e ferramentas externas para conformidade
- **Security linting**: Use ShellCheck com regras focadas em segurança ativadas
- **Privilege analysis**: Audite scripts para requisitos desnecessários de root/sudo
- **Input sanitization**: Valide todas as entradas externas contra listas de permissão
- **Audit logging**: Faça log de todas as operações relevantes de segurança para syslog
- **Container security**: Verifique ambientes de execução de script para vulnerabilidades

## Observabilidade e Logging

- **Structured logging**: Saída JSON para sistemas de agregação de log
- **Log levels**: Implemente DEBUG, INFO, WARN, ERROR com verbosidade configurável
- **Syslog integration**: Use comando `logger` para integração de log de sistema
- **Distributed tracing**: Adicione IDs de rastreamento para correlação de fluxo de trabalho multi-script
- **Metrics export**: Saída de métricas em formato Prometheus para monitoramento
- **Error context**: Inclua stack traces, informações de ambiente em logs de erro
- **Log rotation**: Configure rotação de arquivo de log para scripts de longa duração
- **Performance metrics**: Rastreie tempo de execução, uso de recursos, latência de chamada externa
- Example: `log_info() { logger -t "$SCRIPT_NAME" -p user.info "$*"; echo "[INFO] $*" >&2; }`

## Checklist de Qualidade

- Scripts passam em análise estática ShellCheck com supressões mínimas
- Código é formatado consistentemente com shfmt usando opções padrão
- Cobertura abrangente de testes com Bats incluindo casos extremos
- Todas as expansões de variáveis são adequadamente entre aspas
- Tratamento de erro cobre todos os modos de falha com mensagens significativas
- Recursos temporários são limpos apropriadamente com traps EXIT
- Scripts suportam `--help` e fornecem informações de uso claras
- Validação de entrada previne ataques de injeção e lida com casos extremos
- Scripts são portáveis entre plataformas alvo (Linux, macOS)
- Desempenho é adequado para workloads e tamanhos de dados esperados

## Saída

- Scripts Bash prontos para produção com práticas de programação defensiva
- Suites de teste abrangentes usando bats-core ou shellspec com saída TAP
- Configurações de pipeline CI/CD (GitHub Actions, GitLab CI) para testes automatizados
- Documentação gerada com shdoc e páginas de man com shellman
- Layout de projeto estruturado com funções de biblioteca reutilizáveis e gerenciamento de dependência
- Arquivos de configuração de análise estática (.shellcheckrc, .shfmt.toml, .editorconfig)
- Benchmarks de desempenho e relatórios de profiling para fluxos de trabalho críticos
- Revisão de segurança com SAST, varredura de secrets e relatórios de vulnerabilidade
- Utilitários de debugging com modos de rastreamento, logging estruturado e observabilidade
- Guias de migração para upgrades Bash 3→5 e modernização de legado
- Configurações de distribuição de pacote (fórmulas Homebrew, specs deb/rpm)
- Imagens de container para ambientes de execução reproduzíveis

## Ferramentas Essenciais

### Análise Estática e Formatação
- **ShellCheck**: Analisador estático com configuração `enable=all` e `external-sources=true`
- **shfmt**: Formatter de script shell com config padrão (`-i 2 -ci -bn -sr -kp`)
- **checkbashisms**: Detecte construções bash-specific para análise de portabilidade
- **Semgrep**: SAST com regras customizadas para problemas de segurança específicos de shell
- **CodeQL**: Varredura de segurança do GitHub para scripts shell

### Frameworks de Teste
- **bats-core**: Fork mantido do Bats com recursos modernos e desenvolvimento ativo
- **shellspec**: Framework de teste estilo BDD com assertions ricas e mocking
- **shunit2**: Framework de teste estilo xUnit para scripts shell
- **bashing**: Framework de teste com suporte a mocking e isolamento de teste

### Ferramentas de Desenvolvimento Moderno
- **bashly**: Gerador de framework CLI para construir aplicações de linha de comando
- **basher**: Gerenciador de pacote Bash para gerenciamento de dependência
- **bpkg**: Gerenciador de pacote bash alternativo com interface tipo npm
- **shdoc**: Gere documentação markdown a partir de comentários de script shell
- **shellman**: Gere páginas de man a partir de scripts shell

### CI/CD e Automação
- **pre-commit**: Framework de multi-linguagem pre-commit hook
- **actionlint**: Linter de workflow GitHub Actions
- **gitleaks**: Varredura de secrets para prevenir vazamento de credencial
- **Makefile**: Automação para lint, format, test e fluxos de trabalho de release

## Armadilhas Comuns a Evitar

- `for f in $(ls ...)` causando bugs de word splitting/globbing (use `find -print0 | while IFS= read -r -d '' f; do ...; done`)
- Expansões de variáveis sem aspas levando a comportamento inesperado
- Depender de `set -e` sem proper error trapping em fluxos complexos
- Usar `echo` para saída de dados (prefira `printf` para confiabilidade)
- Ausência de cleanup traps para arquivos e diretórios temporários
- População de array insegura (use `readarray`/`mapfile` em vez de command substitution)
- Ignorar tratamento de arquivo binary-safe (sempre considere separadores NUL para nomes de arquivo)

## Gerenciamento de Dependência

- **Package managers**: Use `basher` ou `bpkg` para instalar dependências de script shell
- **Vendoring**: Copie dependências para projeto para builds reproduzíveis
- **Lock files**: Documente versões exatas de dependências usadas
- **Checksum verification**: Verifique integridade de scripts externos originados
- **Version pinning**: Bloqueie dependências a versões específicas para prevenir breaking changes
- **Dependency isolation**: Use diretórios separados para diferentes conjuntos de dependência
- **Update automation**: Automatize atualizações de dependência com Dependabot ou Renovate
- **Security scanning**: Verifique dependências para vulnerabilidades conhecidas
- Example: `basher install username/repo@version` ou `bpkg install username/repo -g`

## Técnicas Avançadas

- **Error Context**: Use `trap 'echo "Error at line $LINENO: exit $?" >&2' ERR` para debugging
- **Safe Temp Handling**: `trap 'rm -rf "$tmpdir"' EXIT; tmpdir=$(mktemp -d)`
- **Version Checking**: `(( BASH_VERSINFO[0] >= 5 ))` antes de usar recursos modernos
- **Binary-Safe Arrays**: `readarray -d '' files < <(find . -print0)`
- **Function Returns**: Use `declare -g result` para retornar dados complexos de funções
- **Associative Arrays**: `declare -A config=([host]="localhost" [port]="8080")` para estruturas de dados complexas
- **Parameter Expansion**: `${filename%.sh}` remove extensão, `${path##*/}` basename, `${text//old/new}` substitui tudo
- **Signal Handling**: `trap cleanup_function SIGHUP SIGINT SIGTERM` para shutdown elegante
- **Command Grouping**: `{ cmd1; cmd2; } > output.log` compartilha redirecionamento, `( cd dir && cmd )` usa subshell para isolamento
- **Co-processes**: `coproc proc { cmd; }; echo "data" >&"${proc[1]}"; read -u "${proc[0]}" result` para pipes bidirecionais
- **Here-documents**: `cat <<-'EOF'` com `-` remove tabs iniciais, quotes previnem expansão
- **Process Management**: `wait $pid` para aguardar job em background, `jobs -p` lista PIDs em background
- **Conditional Execution**: `cmd1 && cmd2` executa cmd2 apenas se cmd1 sucede, `cmd1 || cmd2` executa cmd2 se cmd1 falha
- **Brace Expansion**: `touch file{1..10}.txt` cria múltiplos arquivos eficientemente
- **Nameref Variables**: `declare -n ref=varname` cria referência a outra variável (Bash 4.3+)
- **Improved Error Trapping**: `set -Eeuo pipefail; shopt -s inherit_errexit` para tratamento de erro abrangente
- **Parallel Execution**: `xargs -P $(nproc) -n 1 command` para processamento paralelo com contagem de núcleos CPU
- **Structured Output**: `jq -n --arg key "$value" '{key: $key}'` para geração JSON
- **Performance Profiling**: Use `time -v` para uso de recurso detalhado ou `TIMEFORMAT` para timing customizado

## Referências e Leitura Adicional

### Guias de Estilo e Melhores Práticas
- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) - Guia de estilo abrangente cobrindo quoting, arrays e quando usar shell
- [Bash Pitfalls](https://mywiki.wooledge.org/BashPitfalls) - Catálogo de erros Bash comuns e como evitá-los
- [Bash Hackers Wiki](https://wiki.bash-hackers.org/) - Documentação Bash abrangente e técnicas avançadas
- [Defensive BASH Programming](https://www.kfirlavi.com/blog/2012/11/14/defensive-bash-programming/) - Padrões modernos de programação defensiva

### Ferramentas e Frameworks
- [ShellCheck](https://github.com/koalaman/shellcheck) - Ferramenta de análise estática e documentação wiki extensa
- [shfmt](https://github.com/mvdan/sh) - Formatter de script shell com documentação detalhada de flags
- [bats-core](https://github.com/bats-core/bats-core) - Framework de teste Bash mantido
- [shellspec](https://github.com/shellspec/shellspec) - Framework de teste estilo BDD para scripts shell
- [bashly](https://bashly.dannyb.co/) - Gerador de framework CLI moderno para Bash
- [shdoc](https://github.com/reconquest/shdoc) - Gerador de documentação para scripts shell

### Segurança e Tópicos Avançados
- [Bash Security Best Practices](https://github.com/carlospolop/PEASS-ng) - Padrões de script shell focados em segurança
- [Awesome Bash](https://github.com/awesome-lists/awesome-bash) - Lista curada de recursos e ferramentas Bash
- [Pure Bash Bible](https://github.com/dylanaraps/pure-bash-bible) - Coleção de alternativas pure bash a comandos externos