> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Escaneamento de Contêineres

> Escaneie imagens de contêiner construídas em busca de vulnerabilidades em pacotes do sistema operacional e dependências embutidas, com descobertas por camada e orientação de upgrade de imagem base.

<h2 id="how-it-works">
  Como Funciona
</h2>

O Escaneamento de Contêineres do ZeroPath analisa as imagens de contêiner que você realmente entrega. Em vez de inspecionar
apenas o código-fonte a partir do qual um repositório é construído, ele examina uma imagem construída — obtida por sua
referência de registro ou enviada como um arquivo local — analisando o sistema operacional e tudo o que está empacotado
sobre ele em busca de vulnerabilidades conhecidas. Imagens públicas, registros privados (com credenciais) e imagens
air-gapped compartilhadas como um arquivo `docker save` são todos suportados. As descobertas são exibidas na seção
**Supply Chain** existente, ao lado da análise de dependências, para que o risco em nível de imagem e em nível de
código-fonte fiquem em um só lugar.

<Columns cols={3}>
  <Card title="Escaneamento em Nível de Imagem" icon="box">
    Escaneia uma imagem construída — obtida por referência de registro, incluindo registros privados com credenciais,
    ou enviada como um arquivo local — e analisa os pacotes do sistema operacional e as dependências embutidas nela,
    não apenas o código-fonte a partir do qual ela foi construída.
  </Card>

  <Card title="Atribuição por Camada" icon="layer-group">
    Vincula cada vulnerabilidade à camada da imagem que a introduziu, para que você possa distinguir problemas herdados
    da imagem base daqueles adicionados pelo seu build.
  </Card>

  <Card title="Monitoramento Contínuo" icon="rotate">
    Re-escaneia imagens monitoradas em um cronograma para que CVEs recém-divulgadas apareçam sem uma nova execução manual.
  </Card>
</Columns>

<h2 id="end-to-end-flow">
  Fluxo de Ponta a Ponta
</h2>

<Steps>
  <Step title="Imagem Enviada">
    Você aponta o ZeroPath para uma imagem construída. O ZeroPath resolve uma referência de registro e obtém a
    imagem — autenticando-se com as credenciais de registro que você fornece para registros privados — ou lê
    um arquivo de imagem local que você envia, no caso de imagens air-gapped que não podem ser obtidas de um registro.
  </Step>

  <Step title="Extração de Camadas">
    A imagem é desempacotada camada por camada. O ZeroPath registra qual camada contribui com cada arquivo, para que as
    descobertas possam depois ser atribuídas à camada que as introduziu.
  </Step>

  <Step title="Inventário de Pacotes">
    O ZeroPath inventaria os pacotes do sistema operacional e as dependências de aplicação embutidas na
    imagem, construindo um panorama completo de tudo o que é entregue dentro dela — incluindo pacotes que nunca
    aparecem nos manifestos do seu código-fonte.
  </Step>

  <Step title="Correspondência de Vulnerabilidades">
    Os pacotes inventariados são comparados com inteligência de vulnerabilidades para identificar problemas conhecidos em
    pacotes do sistema operacional e dependências embutidas.
  </Step>

  <Step title="Descobertas por Camada e Severidade">
    Cada descoberta é atribuída à camada que a introduziu e recebe uma classificação de severidade (Critical / High /
    Medium / Low), para que você veja imediatamente se um problema veio da sua imagem base ou das suas próprias
    etapas de build.
  </Step>

  <Step title="Orientação de Upgrade de Imagem Base">
    O ZeroPath detecta a base da imagem e, quando existe uma base estável mais nova da mesma distribuição,
    escaneia essa candidata e a recomenda — informando quantas das descobertas atuais o upgrade
    removeria, para que você corrija o maior número de vulnerabilidades com o mínimo de mudanças.
  </Step>

  <Step title="Resultados Entregues">
    As descobertas são exibidas na seção Supply Chain no seu dashboard, na API e nas integrações.
    As descobertas de escaneamento de contêiner também aparecem na lista principal de Issues junto com os resultados de SAST e SCA, oferecendo uma visão unificada de todas as descobertas de segurança da sua organização.
    Imagens monitoradas são reavaliadas conforme seu cronograma à medida que novas vulnerabilidades são divulgadas.
  </Step>
</Steps>

<h2 id="container-images-dashboard">
  Dashboard de Imagens de Contêiner
</h2>

A seção Containers está organizada em duas páginas: uma visão geral em **Dashboard** e uma lista em **Images**.

<h3 id="dashboard">
  Dashboard
</h3>

O Dashboard fornece uma visão geral rápida de todas as imagens de contêiner rastreadas na sua
organização, incluindo:

* **Contagens de imagens** — total de imagens rastreadas, quantas são monitoradas em um cronograma, quantas estão
  sendo escaneadas no momento e quantas tiveram falha no escaneamento mais recente.
* **Descobertas por severidade** — um detalhamento do total de descobertas no escaneamento mais recente de cada imagem, agrupadas
  em Critical, High, Medium, Low e Informational.
* **Oportunidades de upgrade de imagem base** — imagens em que uma base mais nova da mesma distribuição
  removeria descobertas, classificadas pelo número de descobertas que o upgrade resolve.
* **Imagens mais vulneráveis** — uma lista classificada das imagens com as maiores contagens de descobertas.

<h3 id="images-list">
  Lista de Imagens
</h3>

A página Images lista todas as imagens de contêiner rastreadas, com busca, filtros e paginação. As imagens
são agrupadas por repositório para que você veja rapidamente quais imagens pertencem a qual projeto;
imagens avulsas (não vinculadas a um repositório) ficam reunidas em seu próprio grupo.

Você pode enviar novas imagens para escaneamento diretamente dessa página usando o botão **Scan image**,
que abre um diálogo com dois modos:

* **Registry image** — informe uma referência de imagem (ex.: `ghcr.io/acme/api:1.4`), forneça opcionalmente
  credenciais de registro privado e, opcionalmente, defina um cronograma de monitoramento (expressão cron, UTC).
* **Upload archive** — envie um tarball do `docker save` (`.tar`) para imagens que não podem ser obtidas
  de um registro. Uma barra de progresso acompanha o envio.

Em ambos os modos você pode, opcionalmente, anexar a imagem a um dos seus repositórios. Em caso de sucesso, o
diálogo navega para a página de detalhes da nova imagem.

<h3 id="image-detail">
  Detalhes da Imagem
</h3>

Clicar em uma imagem abre uma página de detalhes com três abas:

* **Overview** — histograma de severidade (Critical / High / Medium / Low), contagens de descobertas corrigíveis e resolvidas,
  recomendação de upgrade de imagem base (quando disponível), metadados da imagem (digest, tamanho, data de build,
  contagem de descobertas, imagem base detectada) e um detalhamento de camadas mostrando quais camadas são da imagem
  base e quais são camadas da aplicação.
* **Vulnerabilities** — uma lista pesquisável e filtrável de cada CVE encontrada no escaneamento mais recente da imagem.
  Você pode buscar por ID de CVE ou nome de pacote e filtrar por severidade (Critical, High), status de corrigibilidade
  ou status aberto. Clicar em uma CVE abre os detalhes completos da issue com o mesmo fluxo de triagem usado
  no restante do ZeroPath (mudanças de status, geração de patches, exportação para o Jira etc.). Links diretos para
  descobertas individuais podem ser compartilhados pela URL.
* **Settings** — configure um cronograma de monitoramento (expressão cron, UTC) para imagens de registro e
  vincule ou revincule a imagem a um repositório da sua organização.

Na página de detalhes você também pode:

* **Re-scan now** — obter e re-escanear uma imagem de registro imediatamente. (Arquivos enviados não podem ser
  re-escaneados porque o tarball original não é retido.)
* **Delete** — remover permanentemente a imagem rastreada e todo o seu histórico de escaneamentos.

Quando um escaneamento falha, um banner de falha é exibido com orientação para tentar novamente. Quando uma imagem está na fila mas
ainda não foi escaneada, a página mostra um placeholder até que os resultados estejam disponíveis.

<h2 id="managing-container-images">
  Gerenciando Imagens de Contêiner
</h2>

Pelo dashboard ou pela API, você pode:

* **Listar imagens** com busca e paginação baseada em cursor, opcionalmente filtradas por repositório.
* **Ver detalhes da imagem**, incluindo o resumo do escaneamento mais recente, o status da fila e o cronograma de monitoramento.
* **Habilitar o monitoramento** com um cronograma cron para que a imagem seja re-escaneada de forma recorrente.
* **Desabilitar o monitoramento** para voltar a escanear apenas no envio.
* **Vincular a um repositório** para reatribuir uma imagem de um repositório a outro (ambos precisam estar na sua
  organização e ser acessíveis a você).
* **Excluir uma imagem** para parar de rastreá-la completamente e remover todo o seu histórico de escaneamentos.

<h2 id="running-scans">
  Executando Escaneamentos
</h2>

<Tabs>
  <Tab title="Escaneamento Único">
    Execute um único escaneamento de uma imagem construída para obter um retrato imediato de suas vulnerabilidades. Essa é a
    escolha certa para verificações pontuais, gates de CI/CD sobre uma imagem recém-construída ou para avaliar uma imagem antes
    de promovê-la.

    ```bash theme={null}
    zeropath container test <image>
    ```

    O escaneamento obtém a imagem referenciada, inventaria seus pacotes de sistema operacional e dependências embutidas e
    retorna descobertas por camada com orientação de upgrade de imagem base.
  </Tab>

  <Tab title="Registro Privado">
    Para escanear uma imagem hospedada em um registro privado, informe as credenciais do registro e o ZeroPath se autentica
    ao obter a imagem. As credenciais são transmitidas via TLS e armazenadas criptografadas.

    ```bash theme={null}
    zeropath container test <image> \
      --registry-username <username> \
      --registry-token <token>
    ```

    Use um token de acesso ao registro ou um token de robô/conta de serviço em vez de uma senha pessoal, quando
    seu registro oferecer suporte a isso.
  </Tab>

  <Tab title="Arquivo Local (Air-Gapped)">
    Para imagens que não podem ser obtidas de um registro — ambientes air-gapped, ou imagens que nunca saem de um host de build —
    exporte a imagem para um tarball com `docker save` e envie esse arquivo diretamente. Nenhum acesso a registro
    é necessário.

    ```bash theme={null}
    # Export the built image to a tarball
    docker save -o image.tar <image>

    # Scan the uploaded archive, giving it a label to identify it in results
    zeropath container test --file image.tar --name <label>
    ```

    O ZeroPath lê o arquivo enviado, inventaria seus pacotes de sistema operacional e dependências embutidas e
    retorna as mesmas descobertas por camada e orientação de upgrade de imagem base de uma imagem obtida de registro.

    <Note>
      Arquivos enviados são escaneados uma única vez e não podem ser monitorados em um cronograma — não há referência
      de registro para obter novamente. Use uma imagem de registro (`zeropath container monitor <image>`) para
      re-escaneamentos recorrentes.
    </Note>
  </Tab>

  <Tab title="Escaneamento Monitorado">
    Registre uma imagem para re-escaneamentos recorrentes, de modo que ela seja verificada continuamente contra a inteligência
    de vulnerabilidades mais recente. Uma imagem que está limpa hoje pode se tornar vulnerável no momento em que uma nova CVE é
    divulgada — o monitoramento revela esses problemas sem uma nova execução manual.

    ```bash theme={null}
    # Monitor an image on the default schedule
    zeropath container monitor <image>

    # Monitor an image on a custom schedule (crontab expression)
    zeropath container monitor <image> --schedule "0 6 * * *"
    ```

    Imagens monitoradas mantêm sua orientação de upgrade de imagem base atualizada, para que você sempre saiba qual é a única
    mudança que resolve o maior número de descobertas nas suas imagens em execução.
  </Tab>
</Tabs>

<h2 id="key-capabilities">
  Principais Capacidades
</h2>

<Columns cols={2}>
  <Card title="Cobertura de Pacotes do Sistema Operacional" icon="box">
    Detecta vulnerabilidades conhecidas nos pacotes de sistema instalados na sua imagem base e nas etapas de build.
  </Card>

  <Card title="Detecção de Dependências Embutidas" icon="cubes">
    Encontra dependências de aplicação vulneráveis copiadas ou instaladas na imagem durante o build —
    incluindo pacotes que nunca aparecem nos manifestos do seu código-fonte.
  </Card>

  <Card title="Atribuição por Camada" icon="layer-group">
    Cada vulnerabilidade é vinculada à camada que a introduziu, distinguindo problemas herdados da imagem
    base daqueles adicionados pelo seu build.
  </Card>

  <Card title="Recomendações de Upgrade de Imagem Base" icon="arrow-up-right-dots">
    Detecta a base da imagem e, quando existe uma base estável mais nova da mesma distribuição, escaneia essa
    candidata e informa quantas descobertas o upgrade removeria — de modo que uma única mudança pode eliminar muitos
    problemas de uma vez.
  </Card>

  <Card title="Suporte a Registro Privado" icon="lock">
    Escaneia imagens em registros privados usando as credenciais de registro que você fornece. As credenciais são enviadas
    via TLS e armazenadas criptografadas.
  </Card>

  <Card title="Envio de Arquivo Local" icon="file-zipper">
    Escaneia imagens air-gapped que não podem ser obtidas de um registro por meio do envio direto de um arquivo `docker save`, sem
    necessidade de acesso a registro.
  </Card>

  <Card title="Monitoramento Agendado" icon="rotate">
    Re-escaneia imagens monitoradas em um cronograma recorrente para que CVEs recém-divulgadas apareçam automaticamente.
  </Card>

  <Card title="Visão Unificada de Supply Chain" icon="sitemap">
    Descobertas em nível de imagem aparecem na mesma seção Supply Chain que a análise de dependências, oferecendo o
    panorama completo do que é entregue em produção.
  </Card>

  <Card title="Envio de Arquivo via API" icon="upload">
    Envie um tarball de imagem de contêiner pela API em partes (chunks) para ambientes air-gapped onde
    o acesso a registro não está disponível. O fluxo de envio em partes lida com arquivos grandes de forma confiável.
  </Card>
</Columns>

<h2 id="adoption-checklist">
  Checklist de Adoção
</h2>

<Steps>
  <Step title="Identifique as Imagens que Você Entrega">
    Liste as imagens construídas que rodam em produção — esses são os artefatos que o Escaneamento de Contêineres analisa por
    referência de registro.
  </Step>

  <Step title="Execute um Escaneamento Único">
    Use `zeropath container test <image>` para obter um retrato imediato das vulnerabilidades de uma imagem.
  </Step>

  <Step title="Revise as Descobertas por Camada">
    Inspecione as descobertas na seção Supply Chain, usando a atribuição por camada para separar problemas herdados
    da imagem base daqueles introduzidos pelo seu build.
  </Step>

  <Step title="Aplique as Recomendações de Upgrade de Imagem Base">
    Quando o ZeroPath recomendar uma base mais nova, avalie quantas descobertas o upgrade removeria e adote-a
    para eliminar a maior parcela de descobertas com uma única mudança.
  </Step>

  <Step title="Habilite o Monitoramento">
    Registre as imagens de produção com `zeropath container monitor <image>` para que CVEs recém-divulgadas apareçam
    automaticamente em um cronograma.
  </Step>
</Steps>