> ## 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. # Scans de Código Sob Demanda (Beta) > Envie diffs, arquivos e trechos de código para revisão assíncrona de segurança 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. ```bash theme={null} 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`: ```json theme={null} { "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. ```bash theme={null} 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. ```bash theme={null} 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: ```json theme={null} { "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

```json theme={null} { "kind": "diff", "diff": "diff --git a/api.ts b/api.ts\n..." } ```

Arquivo

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

Arquivos

```json theme={null} { "kind": "files", "files": [ { "path": "src/api.ts", "language": "typescript", "content": "..." } ] } ```

Snippets

```json theme={null} { "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. ```json theme={null} { "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. ```bash theme={null} # 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. ```bash theme={null} 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.