Scans de Código Sob Demanda (Beta)

Os Scans de Código Sob Demanda estão atualmente em beta. A API está disponível para fluxos de trabalho iniciais de CLI, IDE, pre-commit e integrações personalizadas, mas o comportamento, os limites e os campos de resposta podem mudar antes da disponibilidade geral.

Visão Geral

Os Scans de Código Sob Demanda permitem enviar pequenas unidades de código para análise de segurança pela ZeroPath sem iniciar um scan completo do repositório. Use-os quando quiser feedback rápido a partir de uma CLI, integração com IDE, hook de pre-commit, job de CI ou ferramenta personalizada. Você pode enviar:

Um diff do Git
Um único arquivo
Vários arquivos
Um ou mais trechos de código

O scan é executado de forma assíncrona. Envie um job, consulte o status dele e, em seguida, busque os resultados.

Os Scans de Código Sob Demanda não são scans completos de repositório. Eles analisam apenas o código que você envia. Os resultados são retornados pela API de scan assíncrono de código e expiram após 7 dias.

Modos de Target

Toda requisição de scan inclui um target. O target controla se a ZeroPath usa o contexto do repositório ou trata o código enviado como independente.

Target	Use quando
`auto`	Recomendado para CLIs, IDEs, hooks de pre-commit e ferramentas personalizadas para desenvolvedores. A ZeroPath usa a URL do remote Git enviada para encontrar um repositório vinculado quando existe exatamente uma correspondência acessível. Caso contrário, o scan é executado de forma independente.
`repository`	Sua integração já conhece o `repositoryId` da ZeroPath e deve exigir o contexto do repositório vinculado.
`standalone`	Você quer explicitamente escanear o código enviado sem o contexto de um repositório vinculado da ZeroPath.

Quando um repositório é resolvido, a ZeroPath pode usar o contexto persistido de repositório, aplicação e modelo de ameaças para melhorar a análise. Scans independentes usam apenas o código enviado, metadados opcionais de target e contexto suplementar opcional.

Enviar um Scan

Chame POST /api/v2/async-code-scans/submit com sua entrada de código e o target.

curl -X POST https://zeropath.com/api/v2/async-code-scans/submit \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: $ZEROPATH_API_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: $ZEROPATH_API_TOKEN_SECRET" \
  -d '{
    "target": {
      "kind": "auto",
      "remoteUrl": "https://github.com/acme/app.git",
      "label": "app"
    },
    "input": {
      "kind": "diff",
      "diff": "diff --git a/api.ts b/api.ts\n..."
    },
    "metadata": {
      "caller": "cli",
      "baseRef": "main",
      "headRef": "feature/auth-check"
    }
  }'

Envios bem-sucedidos retornam 202 Accepted:

{
  "jobId": "7f3f7fd5-7ad0-4e94-99c8-2a78d98e6316",
  "status": "queued",
  "createdAt": "2026-05-17T18:30:00.000Z"
}

Consultar o Status

Chame POST /api/v2/async-code-scans/status com o jobId retornado.

curl -X POST https://zeropath.com/api/v2/async-code-scans/status \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: $ZEROPATH_API_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: $ZEROPATH_API_TOKEN_SECRET" \
  -d '{"jobId": "7f3f7fd5-7ad0-4e94-99c8-2a78d98e6316"}'

Os status públicos são:

queued
running
completed
failed

Jobs vinculados a repositório exigem permissão de visualização do repositório. Jobs independentes podem ser visualizados apenas pelo mesmo token de API ou pelo mesmo usuário que fez o envio.

Buscar os Resultados

Chame POST /api/v2/async-code-scans/results após a conclusão do job.

curl -X POST https://zeropath.com/api/v2/async-code-scans/results \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: $ZEROPATH_API_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: $ZEROPATH_API_TOKEN_SECRET" \
  -d '{"jobId": "7f3f7fd5-7ad0-4e94-99c8-2a78d98e6316"}'

Os resultados incluem vulnerabilidades estruturadas com localização do arquivo, severidade, confiança, identificadores CWE e uma correção opcional:

{
  "jobId": "7f3f7fd5-7ad0-4e94-99c8-2a78d98e6316",
  "status": "completed",
  "codeScanId": null,
  "result": {
    "vulnerabilities": [
      {
        "id": "1e32c0db-0e54-4bf8-8e41-d70ac2b8d72b",
        "title": "Missing authorization check",
        "description": "The submitted handler updates another user's account without verifying ownership.",
        "file": "api.ts",
        "startLine": 42,
        "endLine": 48,
        "vulnerabilityClass": "Broken Access Control",
        "severity": "high",
        "confidence": 8.5,
        "language": "typescript",
        "cwes": ["CWE-862"],
        "fix": {
          "description": "Require the authenticated user to own the account before applying the update."
        }
      }
    ]
  },
  "error": null
}

Os resultados de Scans de Código Sob Demanda são temporários e devem ser consumidos a partir da resposta da API para o job enviado.

Formatos de Entrada

Use exatamente um formato de entrada por requisição.

Diff

{
  "kind": "diff",
  "diff": "diff --git a/api.ts b/api.ts\n..."
}

Arquivo

{
  "kind": "file",
  "path": "src/api.ts",
  "language": "typescript",
  "content": "export async function handler(req) { ... }"
}

Arquivos

{
  "kind": "files",
  "files": [
    {
      "path": "src/api.ts",
      "language": "typescript",
      "content": "..."
    }
  ]
}

Snippets

{
  "kind": "snippets",
  "snippets": [
    {
      "label": "Express route",
      "language": "typescript",
      "content": "app.post('/users/:id', ...)"
    }
  ]
}

Contexto Suplementar

Use additionalContext para informações de contexto que possam ajudar o scanner a interpretar o código enviado.

{
  "additionalContext": "This route is reachable by authenticated tenant admins only."
}

A ZeroPath trata o contexto suplementar como informação de contexto não confiável, e não como instruções para o scanner.

Uso da CLI

A CLI da ZeroPath inclui scan-code para Scans de Código Sob Demanda.

# Scan the current Git working-tree diff
zeropath scan-code --diff

# Scan staged changes
zeropath scan-code --staged

# Scan one source file
zeropath scan-code --file src/api.ts

# Scan multiple source files
zeropath scan-code --files src/api.ts src/auth.ts

# Scan a snippet
zeropath scan-code --snippet "const token = req.query.token"

# Read a snippet from stdin
cat route.ts | zeropath scan-code --stdin --language typescript

Por padrão, a CLI usa target.kind = "auto" e inclui a URL do seu remote Git quando disponível. Use --repository-id para exigir o contexto de um repositório vinculado, ou --standalone para forçar um scan sem contexto de repositório.

Limites

Limite	Valor
Corpo JSON da requisição	768 KiB
Entrada de código enviada	256 KiB
Contexto suplementar	20 KiB
Arquivos por requisição	20
Snippets por requisição	20
Retenção de resultados	7 dias

Requisições acima desses limites retornam 413.

Autenticação

Os Scans de Código Sob Demanda usam os mesmos cabeçalhos de token de API que o restante da API da ZeroPath.

X-ZeroPath-API-Token-Id: YOUR_TOKEN_ID
X-ZeroPath-API-Token-Secret: YOUR_TOKEN_SECRET
Content-Type: application/json

Para targets repository, quem chama deve poder iniciar scans no repositório de destino. Para targets auto, a ZeroPath usa o contexto do repositório apenas quando a URL remota enviada resolve para exatamente um repositório acessível. Para targets standalone, quem chama precisa apenas de contexto autenticado de organização.

Começando

Escaneamento

SCA

Plataforma

Ferramentas de Desenvolvimento

Integrações

Autenticação

Visão Geral

Modos de Target

Enviar um Scan

Consultar o Status

Buscar os Resultados

Formatos de Entrada

Diff

Arquivo

Arquivos

Snippets

Contexto Suplementar

Uso da CLI

Limites

Autenticação

​Visão Geral

​Modos de Target

​Enviar um Scan

​Consultar o Status

​Buscar os Resultados

​Formatos de Entrada

​Diff

​Arquivo

​Arquivos

​Snippets

​Contexto Suplementar

​Uso da CLI

​Limites

​Autenticação

Visão Geral

Modos de Target

Enviar um Scan

Consultar o Status

Buscar os Resultados

Formatos de Entrada

Diff

Arquivo

Arquivos

Snippets

Contexto Suplementar

Uso da CLI

Limites

Autenticação