grepular/foxcageExecute o Firefox em um contêiner Podman rootless com capabilities removidas, rede isolada e armazenamento efêmero para conter fugas da sandbox e evitar o comprometimento do host.
foxcageExecute o Firefox em um contêiner Podman sem root para isolamento de segurança. Seu navegador roda com quase nenhuma capability do Linux, em seu próprio namespace de usuário e de rede, isolado do host — enquanto ainda tem aceleração de GPU completa, áudio e suporte a DRM.
O Firefox já possui um sandbox multiprocesso que isola os renderizadores de conteúdo web usando namespaces do Linux e seccomp-bpf. Para a maioria das ameaças, isso é eficaz. O foxcage adiciona uma segunda parede: se um atacante explorar uma vulnerabilidade que escape do sandbox do Firefox (o que acontece — existem CVEs para isso), ele cairá dentro de um contêiner bloqueado em vez da sua sessão de usuário completa.
~/.ssh, ~/.gnupg, perfis de navegador de outros navegadores, bancos de dados de gerenciadores de senhas, documentos, código-fonte. No foxcage, o atacante vê apenas o que você montou explicitamente.@tmp deixa zero vestígios no disco após o fechamento da janela — incluindo extensões, estado HSTS, cache de sessão TLS e cache DNS que a Navegação Privada do Firefox ainda persiste. Várias gaiolas @tmp rodam simultaneamente sem interferir umas nas outras.~/.config/autostart, ~/.bashrc, cron ou em qualquer outro lugar para sobreviver a uma reinicialização. O contêiner efêmero do foxcage (--rm) significa que nada persiste a menos que você o tenha montado via bind.localhost. No Firefox puro, uma fuga de sandbox tem acesso total à rede. (Use [network] mode = "host" se uma gaiola precisar de acesso a localhost, por exemplo, para desenvolvimento local — mas veja a ressalva em "Rede": o modo host também expõe os sockets Unix abstratos do host.)CAP_SYS_CHROOT, e bloqueia a aquisição de novos privilégios. Binários setuid, exploits de kernel via syscalls obscuras e caminhos de escalonamento semelhantes são cortados.profile, downloads_dir, montagens bind extras) é totalmente acessível a um navegador comprometido. Se você montar um diretório de perfil do host, um atacante pode adulterá-lo assim como no Firefox puro.O contêiner roda com:
CAP_SYS_CHROOT adicionada de volta para o sandbox de conteúdo do Firefox; CAP_SETUID/CAP_SETGID adicionadas temporariamente quando init.root está configurado)no-new-privileges para impedir escalonamento de privilégios--userns keep-id)/dev/shm privado (não compartilhado com o host) — tamanho configurável via shm_sizenetwork.dns)XDG_RUNTIME_DIR são montados via bind (Wayland, PulseAudio, PipeWire e o proxy D-Bus filtrado) — o diretório de runtime completo do host nunca é expostoxdg-dbus-proxy filtrado rodando no host. Apenas , , e (para forks) o namespace próprio do fork (por exemplo, ) são alcançáveis — serviços de sessão como o keyring e o agente SSH/GPG são bloqueadosCada opção [network] e [mounts] que você habilitar troca algum isolamento por conveniência. Os padrões são a configuração mais restritiva que ainda oferece um navegador utilizável.
sudo apt install passt) — a menos que network.mode = "host"sudo apt install xdg-dbus-proxy)/dev/dri, o foxcage avisa e o Firefox renderiza em software. Drivers VA-API para Intel, AMD e nouveau são instalados na imagem, então a decodificação de vídeo por hardware funciona sem pacotes de driver do host — veja Decodificação de vídeo por hardwareExecute o foxcage como seu usuário normal de desktop, não como root ou via sudo — o sandbox mapeia seu usuário para dentro do contêiner, e rodar como root remove o isolamento para o qual o foxcage existe. Ele se recusa a iniciar como root.
Ambiente testado: Debian 13 (Trixie) com GNOME 3. Outras distribuições Linux e compositores Wayland podem funcionar, mas não foram testados.
O foxcage é um único script Python sem dependências fora da biblioteca padrão do Python. Copie-o para um diretório no seu PATH:```sh
sudo cp foxcage /usr/local/bin/foxcage
Ou para uma instalação local do usuário:```sh
cp foxcage ~/.local/bin/foxcage
Certifique-se de que o script é executável (chmod +x foxcage).
Verifique qual revisão você tem com foxcage --version — útil ao relatar um problema, já que o foxcage é instalado copiando um único arquivo.
./foxcage
Na primeira execução, o script cria a imagem do contêiner (baixa o Firefox da Mozilla, instala dependências mínimas do Debian) e então inicia o Firefox. Nas execuções subsequentes, o foxcage verifica se há atualizações do Firefox e reconstrói a imagem automaticamente quando uma nova versão está disponível. A imagem também é reconstruída periodicamente (a cada 7 dias por padrão) para incorporar atualizações de pacotes do sistema. Se a verificação de atualização falhar (erro de rede, tempo limite), um aviso é registrado e a imagem existente é usada — a inicialização nunca é bloqueada.
Passe argumentos para o Firefox:```sh
./foxcage https://example.com
Combine uma gaiola nomeada com flags do Firefox:```sh ./foxcage @work --kiosk https://example.com
Se uma gaiola já estiver em execução, o URL abre num novo separador no navegador existente, em vez de iniciar um segundo contentor. Executar `foxcage` (ou `foxcage @cage`) sem URL contra uma gaiola em execução termina de forma limpa com uma mensagem "a gaiola já está em execução" — o foxcage não consegue elevar uma janela Wayland existente a partir de fora do contentor, por isso nem tenta.
As flags por lançamento **não** se aplicam quando uma gaiola já está em execução. `--dns`, `--ipv4-only`, `--lifetime`, `--color` e `--fork` são consumidos quando o contentor arranca, e as definições de um contentor em execução não podem ser alteradas a partir de fora, por isso são ignoradas com um aviso. Feche a gaiola e volte a executar para as aplicar.
> Use a chave de configuração `private_browsing` para sessões em modo privado — *não* a flag CLI crua `--private-window` do Firefox. A chave de configuração define o modo privado em toda a sessão (`browser.privatebrowsing.autostart`), para que invocações subsequentes de `foxcage @cage URL` possam reabrir em separadores. `--private-window` como passagem direta do Firefox tornaria privada apenas a primeira janela e quebraria o comportamento de reabrir em separador acima.
>
> **Aviso:** sessões ativadas através de `private_browsing = true` não mostram os indicadores visuais habituais de janela privada do Firefox (barra de acento roxa, ícone de máscara, "(Navegação Privada)" no título). Isso acontece porque todas as janelas da sessão são privadas, pelo que o Firefox não tem nenhuma janela não privada para contrastar visualmente — ele suprime o indicador. A sessão *é* genuinamente privada; verifique se quiser visitando `about:privatebrowsing` na gaiola (mostra a página padrão de informações de Navegação Privada) ou `about:config` e confirmando `browser.privatebrowsing.autostart = true`.
### Navegação efémera com `@tmp`
Para links pontuais que não devem deixar rasto, use a gaiola reservada `tmp`:```sh
./foxcage @tmp https://somewhere-suspicious.example
Cada lançamento @tmp é um Firefox novo e descartável, sem perfil persistente. Quando a janela fecha, tudo desaparece — cookies, cache, histórico, extensões, estado HSTS, cache de sessão TLS, cache DNS, estado de abas salvo. Isso vai além da Navegação Privada do Firefox, que ainda persiste extensões e uma boa parte do estado em disco.
Várias gaiolas @tmp são executadas simultaneamente, cada uma isolada das outras. A barra de menus mostra FoxCage - tmp (<id curto>) para que você possa distinguir janelas efêmeras concorrentes.
Gaiolas efêmeras abrem uma página em branco na inicialização e novas abas em branco — a página inicial padrão do Firefox e o conteúdo de novas abas (sites principais, recomendações do Pocket, fluxo de atividades) são puro ruído em um perfil novo que está prestes a ser descartado, então são suprimidos. Gaiolas persistentes mantêm os padrões do Firefox.
Se você quiser um nome significativo em uma sessão descartável (por exemplo, um mergulho em pesquisa que você vai querer reabrir em uma nova aba), use @tmp-<nome>:```sh
./foxcage @tmp-research https://example.com # first call → new window
./foxcage @tmp-research https://another.example # second call → new tab in the existing window
`@tmp-<name>` continua a ser efémero — quando fechas a janela, tudo desaparece. A diferença em relação ao `@tmp` simples é que os segundos arranques com o mesmo nome **reutilizam a janela existente** (tal como as cages persistentes), para que possas adicionar mais separadores mais tarde sem iniciar uma cópia paralela. O `@tmp` simples mantém o seu comportamento de "cada arranque é um descartável novo".
O rótulo da barra de menus mostra o nome que escolheste (`FoxCage - tmp-research`), para que a janela fique identificada de forma significativa.
#### Personalizar os padrões efémeros
Cria `~/.config/foxcage/tmp.toml` para definir os padrões de todas as cages efémeras (tanto o `@tmp` simples como cada `@tmp-<name>`). Por exemplo:```toml
private_browsing = true
lifetime = "30m"
extensions = ["ublock-origin"]
[network]
dns = "cloudflare"
Cada lançamento efémero agora recebe uma janela privada, uBlock Origin, Cloudflare DoH e fecha automaticamente após 30 minutos — com a efemeridade totalmente intacta. Os efémeros nomeados herdam tmp.toml por padrão; se quiseres substituir por nome, cria ~/.config/foxcage/tmp-<name>.toml. Esse ficheiro aplica-se então em vez de tmp.toml — sem fusão, o ficheiro mais específico vence por completo. Copia os padrões partilhados para ele se os quiseres.
Tudo o que podes definir na configuração de uma cage regular funciona aqui, exceto a única chave que derrotaria a própria efemeridade:
profile — erro grave.Ela aponta para um diretório de perfil persistente no host, o que contradiz diretamente o propósito de @tmp. Se quiseres uma cage em sandbox com perfil persistente, usa uma cage nomeada regular (@work, @research, etc.) que não comece com tmp-.
Uma cage pode ter extensões incorporadas na sua imagem e forçadas a instalar em cada lançamento:```toml extensions = ["ublock-origin"]
Coloca isso em `~/.config/foxcage/tmp.toml` e **toda cage descartável já começa com o uBlock Origin em execução** — o que importa, porque uma cage efêmera é, de outra forma, o navegador menos protegido que você tem, usado exatamente nos links em que menos confia. Um perfil `@tmp` novo não tem nenhuma extensão, e instalar uma manualmente é inútil em uma sessão que se destrói ao fechar.
Cada entrada pode ser o nome curto da URL do add-on em addons.mozilla.org, a própria URL da listagem ou o ID do add-on:```toml
extensions = [
"ublock-origin",
"https://addons.mozilla.org/firefox/addon/noscript/",
"[email protected]",
]
Add-ons são resolvidos através da API do addons.mozilla.org no lançamento, baixados durante a construção da imagem e verificados contra o SHA-256 que a AMO publica. A versão resolvida faz parte do Containerfile, então um novo lançamento de uma extensão altera o hash da imagem e dispara uma reconstrução — as extensões são atualizadas da mesma forma que o Firefox, e pela mesma razão: nada é instalado em tempo de execução, então um perfil efêmero novo nunca baixa nada novamente.
Como são instalados por política empresarial em vez de manualmente:
about:addons os mostra como instalados pela sua organização).private_browsing = true. Isso requer Firefox 136 ou ESR 128.8; versões mais antigas ignoram a configuração e deixam o add-on inerte em janelas privadas.Limitações:
.xpi simples é rejeitada.@tmp e cada @tmp-<name> constroem uma única imagem foxcage-tmp, então dar a uma cage efêmera nomeada uma lista de extensions diferente de tmp.toml faz com que as duas se reconstruam uma sobre a outra em lançamentos alternados. Mantenha listas de extensões efêmeras em tmp.toml.A flag --dns (e a chave de configuração equivalente network.dns) aceita três formas:```sh
./foxcage @tmp --dns 1.1.1.1 https://example.com # IP
./foxcage @tmp --dns cloudflare https://example.com # alias
./foxcage @tmp --dns https://dns.nextdns.io/ # custom DoH URI
**Quando o valor corresponde a um provedor conhecido (por alias ou por IP), o foxcage ativa automaticamente o DNS forçado sobre HTTPS para esse provedor.** O TRR do Firefox é definido para o modo 3 (estrito, sem fallback em texto claro) com o endereço de bootstrap preenchido, para que não haja vazamento de resolução não criptografada na inicialização. Você vê um aviso de uma linha no stderr, como `Enabling DNS over HTTPS via Cloudflare`.
Aliases integrados:
| Alias | IP | Filtragem |
|-------|------|-----------|
| `cloudflare` | 1.1.1.1 | nenhuma |
| `cloudflare-security` | 1.1.1.2 | bloqueia malware |
| `cloudflare-family` | 1.1.1.3 | bloqueia malware + conteúdo adulto |
| `google` | 8.8.8.8 | nenhuma |
| `quad9` | 9.9.9.9 | bloqueia malware (padrão do Quad9) |
| `quad9-unfiltered` | 9.9.9.10 | nenhuma |
| `adguard` | 94.140.14.14 | bloqueia anúncios + rastreadores |
| `adguard-family` | 94.140.14.15 | anúncios + rastreadores + conteúdo adulto |
| `opendns` | 208.67.222.222 | algumas |
Um IP que não está na tabela (por exemplo, o Pi-hole da sua LAN) permanece apenas em texto claro — nenhum DoH é ativado, pois o foxcage não conhece o endpoint DoH correspondente. Use o formato de URI para isso: `--dns https://pi.hole/dns-query` (com um certificado válido) ativa o DoH e deixa o DNS do contêiner intacto.
O formato de URI ignora a definição do DNS em texto claro do contêiner, então qualquer coisa dentro do contêiner que não seja o Firefox ainda usa o DNS do host. Isso é intencional — `--dns URI` significa "faça o Firefox usar este resolvedor DoH", ponto final.
`--dns` é incompatível com `network.mode = "host"`, que já tem acesso total à rede do host.
### Identificação visual da jaula
Cada jaula nomeada recebe uma cor de destaque na barra de menu para que você possa distinguir as janelas de relance. **Você não precisa configurar nada** — a cor é derivada deterministicamente do nome da jaula (com hash SHA256 convertido em um matiz, com saturação e luminosidade fixas). `@banking`, `@work`, `@personal`, `@tmp-research` recebem cores distintas e estáveis sem que você levante um dedo.
A jaula padrão (anônima) mantém o laranja embutido.
Se quiser substituir a cor derivada automaticamente, defina-a explicitamente:```toml
# ~/.config/foxcage/banking.toml
color = "#dc2626" # red — overrides the auto-derived colour
Aqui está a tradução do conteúdo fornecido:
Para instalar o projectdiscovery/nuclei, execute o seguinte comando:
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
O nuclei pode ser instalado no macOS e Linux usando o Homebrew:
brew install nuclei
O nuclei pode ser instalado e executado usando o Docker:
docker pull projectdiscovery/nuclei:latest
docker run -it projectdiscovery/nuclei:latest
Para instalar o nuclei, baixe o binário apropriado para o seu sistema operacional a partir da página de releases. Alternativamente, você pode usar o script de instalação automática:
curl -sSL https://raw.githubusercontent.com/projectdiscovery/nuclei/main/install.sh | bash
nuclei -h
Isso exibirá a ajuda do nuclei. Aqui estão todas as opções suportadas:
Usage:
nuclei [flags]
Flags:
INPUT:
-u, -target string[] URLs/ hosts de entrada para escanear
-l, -list string Caminho para o arquivo contendo a lista de hosts para escanear (um por linha)
-resume string Retomar a varredura usando o arquivo de reserva (fornecido pelo nuclei)
-sa, -scan-all-ips Escanear todos os IPs associados ao CIDR
-health-check Executar verificações de diagnóstico
Nota: A tradução foi feita preservando toda a estrutura Markdown, comandos, caminhos de arquivo, URLs e identificadores técnicos exatamente como no original. Apenas o texto em linguagem natural foi traduzido para o português.```sh ./foxcage @experiment --color "#10b981" https://example.com # teal, one-off
Aceita hex CSS padrão: `#rgb`, `#rrggbb` ou `#rrggbbaa` (com alfa). As cores derivadas automaticamente são ajustadas para serem visíveis tanto em barras de menu claras quanto escuras (luminosidade fixada em 55%, saturação em 75%), então você não deve precisar substituí-las por motivos de tema.
### Gaiolas com limite de tempo
A flag `--lifetime` (e a chave de configuração equivalente `lifetime`) fecha automaticamente uma gaiola após uma duração definida. O formato é `<número><unidade>` com unidade `s`, `m` ou `h`:```sh
./foxcage @tmp --lifetime 10m https://example.com
./foxcage @work --lifetime 2h
A contagem regressiva começa quando o Firefox realmente inicia dentro da jaula — o tempo de inicialização do contêiner e de construção da imagem não consome seu orçamento. O rótulo da barra de menus da jaula mostra a contagem regressiva junto com a identidade da jaula — ex.: FoxCage - tmp (a3f2b1) | 9m — atualizado uma vez por minuto enquanto houver mais de um minuto restante, e uma vez por segundo no minuto final. Quando a contagem regressiva chega a zero, o Firefox se fecha e o contêiner sai. Se você fechar o Firefox por conta própria antes do tempo de vida expirar, nada de incomum acontece.
Defina um tempo de vida padrão por jaula em sua configuração:```toml
lifetime = "15m" private_browsing = true
`--lifetime` na linha de comando prevalece sobre qualquer valor de configuração.
Force uma reconstrução completa da imagem (rebaixa o Firefox e todos os pacotes do sistema):```sh
./foxcage --rebuild
Um contêiner em execução mantém a imagem a partir da qual foi iniciado, mesmo depois que o foxcage reconstrói a tag da imagem. Se você tentar abrir uma aba em uma cage cuja imagem foi atualizada desde então (por --rebuild, uma atualização do Firefox ou a reconstrução agendada), o foxcage recusa com um erro (também exibido como notificação da área de trabalho) e pede que você saia do Firefox e o reabra — o que inicia um contêiner novo na imagem atual. Sob --rebuild com uma cage ativa, o foxcage avisa antecipadamente, faz a construção e então aplica a mesma verificação.
O foxcage verifica novas versões do navegador a cada inicialização — a API de lançamentos da Mozilla para o Firefox, o endpoint de lançamentos do GitLab para o LibreWolf. Se uma atualização estiver disponível, a imagem do contêiner é reconstruída automaticamente. A imagem também é reconstruída periodicamente (a cada 7 dias por padrão) para incorporar atualizações de segurança do Debian. O atualizador automático integrado do navegador é desativado, pois as atualizações são tratadas no nível da imagem.
Se a verificação de atualização falhar (sem rede, timeout da API), um aviso é exibido e a imagem existente é usada — você sempre pode navegar.
A cadência de atualizações fica no nível superior da configuração; o pinning de versão e canal fica na seção por fork:```toml rebuild_days = 14 # rebuild for base-image updates every 14 days (0 to disable)
[firefox] channel = "beta" # track the beta channel instead of stable (firefox only) version = "149" # pin to Firefox 149.x (latest patch release)
**Fixar uma versão ESR também exige o canal.** O índice de versões da Mozilla lista as versões ESR sem o sufixo `esr` que seus downloads carregam, então um `version = "140"` simples no canal padrão resolve para uma versão que não existe. Defina ambos:```toml
[firefox]
channel = "esr"
version = "140" # → 140.13.0esr
Um pin que não corresponde a nenhuma versão agora é um erro que nomeia o pin, em vez de silenciosamente voltar à versão mais recente. Uma falha temporária ao acessar a API da Mozilla ainda emite um aviso e continua com a imagem existente, para que uma rede instável nunca bloqueie a inicialização.
Pins com sufixo devem ser totalmente qualificados — "140.13.0esr" e "150.0b9" funcionam, "140esr" e "150b9" são rejeitados no carregamento da configuração porque nenhuma versão pode corresponder a eles. O mesmo se aplica às revisões do LibreWolf: "146.0.1-1" funciona, "146-1" não.
Para forçar uma reconstrução completa imediata: ./foxcage --rebuild
O foxcage se recusa a instalar uma compilação do navegador cuja assinatura foi feita por uma subchave de assinatura que o projeto upstream revogou como comprometida (motivo de revogação RFC 4880 0x02). O gpg --verify não faz isso por conta própria: ele imprime um aviso e sai com código 0, então, sem a verificação extra, uma chave de assinatura vazada ainda autenticaria um download adulterado.
Uma recusa tem esta aparência e falha na compilação em vez de instalar:``` foxcage: REFUSING /tmp/SHA512SUMS - signed by 09BEED63F3462A2DFFAB3B875ECB6497C1A20256, which its owner revoked as compromised. This build cannot be trusted; wait for upstream to re-sign this release with a current key.
Não há nada para configurar e nenhuma substituição. Se você encontrar isso, a correção é do projeto upstream: ou fixe uma versão assinada com uma chave atual, ou aguarde a versão afetada ser re-assinada.
A rotação rotineira de chaves é tratada de forma diferente. Uma subchave revogada como substituída, aposentada ou sem motivo declarado não invalida assinaturas feitas *antes* da revogação, então essas versões instalam com um aviso. Uma assinatura datada *após* qualquer revogação é recusada independentemente do motivo declarado.
**Rotação de chaves da Mozilla em agosto de 2026.** A Mozilla revogou a subchave de assinatura `09BEED63…C1A20256` em 2026-08-06 depois que uma cópia não criptografada foi enviada a um repositório privado do GitHub, e a substituiu por `827E6586…76767AA3`. Versões do Firefox assinadas com a subchave antiga — tudo entre 2025-03-13 e 2026-08-06, que no momento da escrita ainda inclui o ESR atual (`140.13.0esr`) e qualquer fixação de `version` nesse intervalo — são recusadas pela verificação acima. Os canais de release e beta não são afetados. O foxcage busca chaves em `keys.openpgp.org` em vez de `keyserver.ubuntu.com` porque este último não serviu nem a subchave substituta nem a revogação por dias após a rotação; um keyserver desatualizado quebraria as builds por completo e reduziria silenciosamente a verificação de revogação a uma operação nula.
### Forks do Firefox (LibreWolf)
O foxcage pode executar um fork do Firefox voltado à privacidade no lugar do Firefox upstream:```toml
fork = "librewolf" # default is "firefox"
[librewolf]
version = "146.0.1-1" # optional pin; partial pins ("146", "146.0.1") also work
Ou por lançamento via CLI:```sh foxcage @tmp --fork librewolf https://example.com
**LibreWolf**: fork do Firefox com foco em privacidade — proteção rigorosa contra rastreamento, DoH, RFP, telemetria desativada por padrão. Tarball Linux assinado do GitLab (`librewolf-community/browser/bsys6`), verificado via GPG contra a chave dos Mantenedores do LibreWolf `662E 3CDD 6FE3 2900 2D0C A5BB 4033 9DD8 2B12 EF16` com uma verificação cruzada do `.sha256sum` correspondente, sob as mesmas [regras de revogação](#revoked-signing-keys) do Firefox. O `librewolf.cfg` incluído no LibreWolf é preservado; o foxcage adiciona suas próprias preferências por cima, em vez de sobrescrever. Os mantenedores rotacionaram sua subchave de assinatura em 2026-04-25 sem informar um motivo; os tarballs atuais foram assinados antes dessa data, então são instalados com um aviso em vez de serem recusados.
**O canal é exclusivo do Firefox**: `firefox.channel = "beta" | "esr"` é rejeitado quando `fork` é qualquer valor diferente de `"firefox"`. O LibreWolf tem um único canal de lançamento.
Alternar `fork` (via config ou `--fork`) altera o hash do Containerfile, o que aciona uma reconstrução na próxima inicialização — sem necessidade de `--rebuild` manual.
#### Compatibilidade de perfis
> **Use um perfil dedicado por fork.** O padrão mais seguro é deixar o foxcage provisionar seu próprio perfil (omitir `profile` da config), ou apontar `profile` para um diretório que você também não abra a partir do host.
- **LibreWolf**: *geralmente* é seguro compartilhar com seu perfil do Firefox do host — o LibreWolf acompanha as versões do Firefox em poucos dias, então conflitos de esquema no `compatibility.ini` são raros. Riscos: (1) apenas o uso sequencial é seguro (o arquivo de bloqueio do Firefox impede aberturas simultâneas); (2) na curta janela após um lançamento estável do Firefox, abrir o Firefox primeiro e depois o LibreWolf pode acionar um diálogo de migração "usado por uma versão mais recente"; (3) recursos que o LibreWolf remove (Sync, Pocket, conta Mozilla) simplesmente não funcionam, mas não corrompem dados.
### Cages nomeadas
Execute instâncias sandbox separadas com sua própria config e perfil do Firefox:```sh
./foxcage @work
Isto carrega ~/.config/foxcage/work.toml e usa uma imagem separada (foxcage-work), um contêiner (foxcage-work) e um volume (foxcage-work-profile). O arquivo de configuração deve existir para gaiolas nomeadas. Os nomes das gaiolas podem conter apenas letras, dígitos, hífens e sublinhados.
Os arquivos de configuração ficam em $XDG_CONFIG_HOME/foxcage/ (padrão: ~/.config/foxcage/).
config.toml — gaiola padrão (opcional, com padrões sensatos sem ele)<nome>.toml — gaiola nomeada, carregada com @<nome> (obrigatório)Chaves de configuração desconhecidas são rejeitadas com um erro. Consulte config.toml.example para todas as opções disponíveis com seus padrões.
profile = "~/.mozilla/firefox/xxxxxxxx.default-release"
downloads_dir = "~/Downloads"
[firefox]
[librewolf]
[network]
[mounts]
bind = [ "~/Documents:ro", ]
[init]
### Perfil do Firefox do host
Para compartilhar um perfil do Firefox do host com a cage, defina `profile` para o diretório do perfil. Encontre o caminho do seu perfil visitando `about:profiles` no Firefox do host — ou apenas aponte para um diretório vazio novo se quiser que a cage comece com um perfil limpo que persista no host.```toml
profile = "~/.mozilla/firefox/xxxxxxxx.default-release"
Apenas este diretório é montado por bind na jaula. Perfis irmãos sob ~/.mozilla/firefox/ e o registro profiles.ini não são expostos — uma jaula comprometida não pode adulterá-los.
Se profile não estiver definido, um volume Podman nomeado armazena o perfil do Firefox (veja "O que persiste" abaixo). Se o mesmo perfil já estiver aberto no Firefox no host, o arquivo de bloqueio por perfil do Firefox causará um conflito — use um perfil dedicado por jaula.
Por padrão, o contêiner usa pasta com loopback do host bloqueado e DNS do host. pasta requer podman 4.4 ou mais recente (é o padrão rootless desde o podman 5.0).
Rede do host remove o isolamento de rede por completo. Use isso quando a jaula precisar alcançar serviços no localhost do host (por exemplo, um servidor de desenvolvimento local, um banco de dados em 127.0.0.1):```toml
[network]
mode = "host"
`dns` não pode ser combinado com `mode = "host"` — a rede host já usa o resolvedor do host.
> **O modo host abre mão de mais do que apenas localhost.** Ele coloca a gaiola no namespace de rede do host, e os sockets Unix abstratos são limitados a esse namespace, e não ao sistema de arquivos. Assim, uma gaiola em modo host pode alcançar diretamente sockets de endereço abstrato no host — incluindo o `@/tmp/.X11-unix/X0` do Xwayland, se você executar X11 ou Xwayland (registro de entrada, apesar de o foxcage ser apenas Wayland), e um barramento de sessão configurado com `unix:abstract=…`, o que contornaria o proxy D-Bus filtrado. Isso é inerente ao compartilhamento da pilha de rede, não algo que o foxcage possa filtrar. Use o modo host quando precisar dele e prefira uma gaiola nomeada que você inicie apenas para esse fim.
**Gaiolas somente IPv4** desabilitam o IPv6 por completo:```toml
[network]
ipv4_only = true
Ou por lançamento com a flag --ipv4-only (forma curta -4, como em ssh/curl/pasta):```sh
./foxcage @tmp -4 https://example.com
Isto executa o pasta em modo apenas IPv4 (`-4`), portanto o contêiner não tem nenhuma pilha IPv6, e adicionalmente define `network.dns.disableIPv6` no Firefox para que ele não resolva registros AAAA — o que importa quando o DoH está habilitado, já que as respostas do DoH ignoram o resolvedor do contêiner. `ipv4_only` não pode ser combinado com `mode = "host"` — a rede host usa a pilha de rede do host diretamente, então desative o IPv6 no host em vez disso.
### Comandos de inicialização
Execute comandos personalizados no momento da construção ou na inicialização do contêiner via `[init]`:
- **`build`** — executa no momento da construção da imagem como root. Use para instalar pacotes ou outras configurações lentas. Alterações nos comandos de construção acionam automaticamente uma reconstrução da imagem.
- **`root`** — executa na inicialização do contêiner como root, antes do Firefox. Use para tarefas rápidas de runtime como root (ajustar permissões, escrever arquivos de configuração).
- **`user`** — executa na inicialização do contêiner como seu usuário, antes do Firefox. Use para criar diretórios, configurar estado de nível de usuário.```toml
[init]
build = [
"apt-get update && apt-get install -y --no-install-recommends fonts-noto-cjk",
"rm -rf /var/lib/apt/lists/*",
]
root = ["chmod 777 /tmp/shared"]
user = ["mkdir -p ~/workspace"]
Todos os três campos são listas de strings de comandos de shell. Se qualquer comando falhar, o contêiner encerra sem iniciar o Firefox.
Nota de segurança: Quando init.root está definido, o contêiner inicia como root com CAP_SETUID e CAP_SETGID adicionados (além do CAP_SYS_CHROOT padrão) para que possa rebaixar de volta ao usuário regular. Essas capacidades são mantidas apenas durante a fase de init como root — após a queda de privilégios, o processo do usuário regular não possui capacidades extras. Sem init.root, o contêiner executa com o conjunto mínimo de capacidades padrão.
Sem configuração, um volume Podman nomeado armazena o perfil do Firefox (favoritos, configurações, extensões, plugin Widevine DRM). Todo o resto é efêmero.
foxcage-profilefoxcage-<name>-profilePara começar do zero, remova o volume:```sh podman volume rm foxcage-profile
Se `profile` estiver definido, o diretório do host é montado diretamente e nenhum volume é criado.
As extensões listadas em `extensions` não fazem parte desse estado: elas vivem na imagem e são reinstaladas a cada inicialização, portanto, remover o volume (ou usar uma gaiola efêmera, que não possui nenhum) não as perde.
### Uso de disco
Cada imagem de gaiola tem cerca de 1 GB. Uma reconstrução reetiqueta a imagem e deixa a anterior para trás como uma entrada `<none>` sem etiqueta, então o foxcage remove a imagem que acabou de deslocar após cada build bem-sucedido. Ele remove apenas essa imagem específica, e nunca uma que uma gaiola em execução ainda esteja usando.
Imagens órfãs antes desse comportamento existir não são limpas retroativamente. Para recuperá-las:```sh
podman images --filter dangling=true # review first
podman image prune # then remove
As atualizações do Firefox são detectadas automaticamente a cada inicialização. Para forçar uma reconstrução completa (por exemplo, para aplicar imediatamente as atualizações de segurança do sistema):```sh ./foxcage --rebuild
## Theming
O foxcage repassa automaticamente o seguinte do host, para que o Firefox no contêiner tenha a aparência e o comportamento de um aplicativo nativo:
- **Fontes.** Fontes do sistema (`/usr/share/fonts`) e fontes do usuário (`~/.local/share/fonts`) são montadas como bind somente leitura. A configuração de fontes de `~/.config/fontconfig` também é repassada.
- **Tema GTK e modo escuro.** Detectados via `GTK_THEME` ou `gsettings` e repassados ao contêiner. A configuração GTK de `~/.config/gtk-3.0` e `~/.config/gtk-4.0` é montada como bind somente leitura.
- **Fuso horário.** O nome do fuso horário do host (detectado a partir de `TZ`, do symlink `/etc/localtime` ou de `/etc/timezone`) é repassado ao contêiner como `TZ`, e `/etc/localtime` é montado como bind somente leitura. Ambos são necessários: o Firefox deriva o fuso horário do JavaScript a partir do *nome* da zona, não do conteúdo do arquivo — sem `TZ`, os sites mostrariam horários em UTC.
- **Locale.** `LANG` é repassado. O locale do host é gerado na imagem do contêiner no momento da compilação.
**Rótulo da cage.** A barra de menus do Firefox exibe "FoxCage" (ou "FoxCage - nome" para cages nomeadas) para que você saiba de imediato que está em uma sessão conteinerizada. A barra de menus está sempre visível por meio de política empresarial.
O contêiner inclui apenas o tema GTK Adwaita. Em desktops GNOME, isso funciona de imediato. Em KDE ou outros desktops, o Firefox recorrerá ao Adwaita se o seu tema GTK (por exemplo, Breeze) não estiver instalado no contêiner. A detecção do modo escuro ainda funciona desde que a preferência seja definida via `gsettings` ou `GTK_THEME`.
## Decodificação de vídeo por hardware (VA-API)
O contêiner tem seu próprio userland, portanto os drivers VA-API instalados no host são
irrelevantes — a imagem traz os seus próprios. `va-driver-all` puxa `i965-va-driver` (Intel
mais antiga) e `mesa-va-drivers` (AMD, nouveau), além de `intel-media-va-driver-non-free`
(Intel Gen8+, o driver iHD) e `libva2`/`libva-drm2`, que o Firefox carrega em tempo de execução.
A decodificação por hardware precisa que `/dev/dri` seja repassado, o que o foxcage faz automaticamente
sempre que o host o possui. Nada para configurar.
O driver Intel é a compilação **non-free**, então a imagem habilita o componente `non-free`
do Debian. O `intel-media-va-driver` livre do Debian é um reempacotamento `+dfsg` com os
kernels de codecs não redistribuíveis removidos, e o que ele perde é a decodificação AV1 — o formato
que o YouTube agora serve por padrão. A compilação livre deixaria o AV1 recorrendo ao software
em toda máquina Intel.
Para verificar se está realmente funcionando, execute `vainfo` dentro de uma cage ativa:```bash
podman exec foxcage-<name> vainfo
Deve listar o driver em uso (iHD na Intel, radeonsi na AMD) e os perfis
suportados — VAProfileH264*, VAProfileVP9Profile0, VAProfileAV1Profile0 e assim por diante.
A verificação equivalente de dentro do navegador é about:support → Media, onde a
coluna Hardware Decoding deve mostrar Supported para H264, VP8, VP9, HEVC e AV1. Com
um vídeo em reprodução, intel_gpu_top no host mostra atividade no mecanismo de vídeo.
A codificação de hardware é separada e, na Intel, vem do mesmo driver: H264 e
HEVC devem mostrar Supported nessa coluna, que é o que o WebRTC usa para o fluxo de
saída da câmera em chamadas de vídeo e o que o MediaRecorder usa. A codificação de VP8, VP9 e AV1
permanece Unsupported — o Firefox só conecta os codificadores VA-API de H264 e HEVC, independentemente
da capacidade da GPU.
Os codecs de áudio (AAC, MP3, Opus, Vorbis, FLAC, Wave) mostram Unsupported em Hardware
Decoding em todas as máquinas — nenhuma GPU de consumo tem um bloco de decodificação de áudio. Essa linha não é
uma configuração incorreta.
Se o vainfo relatar failed to initialize display, o contêiner não consegue abrir
/dev/dri/renderD128. Em um desktop systemd normal, o logind concede ao seu usuário uma ACL nesse
dispositivo, então isso geralmente significa que o foxcage está sendo executado a partir de uma sessão que não
possui o seat (SSH, um TTY diferente).
O DRM Widevine funciona de fábrica. Na primeira visita a um site protegido por DRM, o Firefox baixará o Widevine CDM automaticamente. Isso pode levar um momento.
O foxcage usa um proxy D-Bus filtrado para dar ao Firefox acesso ao XDG Desktop Portal e ao daemon de notificações do host. Esses recursos são seguros porque todo o acesso é mediado pelo usuário — o host mostra diálogos nativos com os quais você deve interagir. Um navegador comprometido não pode acessar silenciosamente os recursos do host.
mailto:, links magnet, etc. abrem via seletor de aplicativos do hostEsses recursos passam dispositivos do host diretamente para o contêiner e estão desativados por padrão — ao contrário dos recursos do portal acima, não há confirmação no lado do host. Um navegador comprometido poderia usar o hardware silenciosamente.```toml webcam = true # /dev/video* — webcam for video calls local_printers = true # CUPS socket — USB printers (network printers work by default) security_keys = true # /dev/hidraw* — FIDO2/U2F hardware keys
## Ainda não suportado
Alguns recursos de plataformas web não funcionam no contêiner devido à falta de integração com o host. Estes estão listados aqui para transparência.
**Bluetooth, USB, serial e NFC.** As APIs Web Bluetooth, WebUSB, Web Serial e WebNFC exigem acesso a dispositivos e serviços de sistema (BlueZ, udev) que não estão disponíveis no contêiner.
**Gamepads e MIDI.** A API Gamepad precisa de acesso a `/dev/input/`. O Web MIDI precisa de acesso ao sequenciador ALSA. Nenhum deles é repassado.
**Instalação de PWA.** Progressive Web Apps não podem ser instalados na área de trabalho do host a partir de dentro do contêiner.
**Acessibilidade.** O suporte a leitores de tela via AT-SPI está desativado (`NO_AT_BRIDGE=1`) — o contêiner não tem conexão com o barramento de acessibilidade do host. A síntese de fala da Web Speech API funciona: o `speech-dispatcher` com o mecanismo `espeak-ng` está instalado na cage e é iniciado automaticamente no primeiro uso, com o áudio roteado através do socket PulseAudio compartilhado.
## Configuração do host
### Recomendado: armazenamento overlay
O Podman sem root pode recorrer ao driver de armazenamento `vfs`, que copia camadas inteiras de imagem em vez de usar montagens overlay. Isso torna a inicialização do contêiner após um build muito mais lenta. Verifique qual driver você tem:```sh
podman info --format '{{.Store.GraphDriverName}} {{.Store.GraphStatus}}'
overlay com Native Overlay Diff:true é o caminho rápido e não precisa de configuração — no kernel 5.13 ou mais recente com um sistema de arquivos de suporte ext4/xfs, o Podman usa overlayfs sem privilégios diretamente. Se é isso que você vê, não há nada a fazer, e instalar fuse-overlayfs não vai ajudar.
Somente se você cair em vfs (kernel antigo, ou um sistema de arquivos de suporte que não consegue fazer overlay sem privilégios) instale fuse-overlayfs e adicione a ~/.config/containers/storage.conf:```toml
[storage]
driver = "overlay"
[storage.options.overlay] mount_program = "/usr/bin/fuse-overlayfs"
Isto é um fallback, não um upgrade: o FUSE roteia cada operação de filesystem através do userspace e é mais lento do que o overlay nativo. Definir `mount_program` em um sistema que suporta overlay nativo piora as coisas, não melhora.
### Definindo o foxcage como seu navegador padrão
Primeiro, certifique-se de que o script `foxcage` esteja em sua localização permanente (ex.: `~/bin/foxcage` ou `/usr/local/bin/foxcage`). O comando de instalação registra o caminho atual do script no arquivo `.desktop`, então movê-lo depois quebrará o launcher.
Em seguida, execute:```sh
foxcage --install
Isto cria um ficheiro .desktop que aponta para a localização atual do script, instala o ícone do foxcage e atualiza as bases de dados do ambiente de trabalho e dos ícones. O FoxCage deverá então aparecer no seu menu de aplicações.
Para definir o foxcage como navegador web predefinido, de modo a que as ligações clicadas noutras aplicações sejam abertas no foxcage:```sh xdg-settings set default-web-browser foxcage.desktop
Se uma gaiola já estiver em execução, os URLs abrem como uma nova aba no navegador existente.
Para desfazer:```sh
foxcage --uninstall
StartupNotify=true está definido no arquivo .desktop, o que informa ao compositor para exibir um cursor de carregamento enquanto o foxcage inicia. Quando uma compilação de imagem é necessária (o que pode levar vários minutos), o foxcage envia uma notificação de desktop para que você saiba que o Firefox está a caminho. Qualquer erro de saída antecipada (erro de digitação na configuração, dependência ausente, nome de cage malformado) também é exibido como uma notificação de desktop, para que usuários que iniciaram pelo desktop não fiquem olhando para nada quando o foxcage falhar sem um terminal anexado. Ambos exigem notify-send (do libnotify-bin no Debian/Ubuntu) — se não estiver instalado, as notificações são silenciosamente ignoradas e o erro ainda vai para o stderr.
Se você preferir criar o arquivo .desktop manualmente, crie ~/.local/share/applications/foxcage.desktop:```ini
[Desktop Entry]
Type=Application
Name=FoxCage
Comment=Firefox in a rootless Podman container
Exec=/path/to/foxcage %u
Icon=foxcage
MimeType=text/html;x-scheme-handler/http;x-scheme-handler/https;
Terminal=false
Categories=Network;WebBrowser;
StartupNotify=true
StartupWMClass=foxcage
Substitua `/path/to/foxcage` pelo caminho real para o script. Registre-o:```sh
update-desktop-database ~/.local/share/applications
A suíte de testes usa pytest + pytest-cov, declarados como dependências apenas de desenvolvimento em requirements-dev.txt.```
pip install -r requirements-dev.txt
pytest
Os testes são totalmente herméticos — sem podman, sem rede, sem sistema de arquivos real além do `tmp_path` do pytest. A suíte exige **100% de cobertura de linhas e branches** (configurado em `pytest.ini` e `.coveragerc`); qualquer linha não coberta, ou lado não executado de uma condicional, faz a execução falhar. O CI executa a suíte a cada push via `.gitlab-ci.yml`.
## Agradecimentos
Este projeto foi desenvolvido por Mike Cardwell, com a assistência de [Claude Code](https://claude.ai/claude-code), a ferramenta de codificação por IA da Anthropic.
## Apoie/Aprecie meu trabalho
- [Bitcoin](bitcoin:1PQLtWnjUi1itHLG6QCQeHM3Nxua8pRsq1): 1PQLtWnjUi1itHLG6QCQeHM3Nxua8pRsq1
- [Paypal](https://www.paypal.me/grepular)
org.freedesktop.Notificationsorg.freedesktop.portal.Desktoporg.mozilla.*org.librewolf.*org.freedesktop.portal.Desktop é permitido como um todo, porque é assim que o seletor de arquivos, "abrir link em outro aplicativo" e o compartilhamento de tela funcionam. Ele também expõe RemoteDesktop (teclado/mouse sintético para toda a sessão), Camera e Location. Esses são controlados pelos diálogos de aprovação do seu próprio desktop, não pelo foxcage — e o prompt de RemoteDesktop se assemelha ao prompt de compartilhamento de tela, então leia os diálogos de aprovação antes de aceitá-los. O xdg-dbus-proxy não tem regra de "negar uma interface", então restringir isso significa enumerar cada interface que o Firefox precisa; veja docs/DESIGN.md para saber por que isso não é feito por padrãoprofile, downloads_dir, [mounts] bind extras) usam nosuid,noexecgpg --verify, que sai com 0 para uma assinatura feita por uma chave revogada e para qualquer chave no chaveiro. O foxcage adicionalmente exige que a assinatura encadeie até a chave primária fixada e recusa qualquer lançamento assinado por uma subchave que seu proprietário revogou como comprometida — veja Chaves de assinatura revogadas--rm) — gravações no sistema de arquivos são perdidas ao sair