{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/guarita-dev/json-schema/guarita-dev-scan-schema.json",
  "title": "Scan",
  "description": "Estado de uma ronda. É o endpoint de polling depois de `POST /scans`.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/guarita-dev-openapi.json#/components/schemas/Scan",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id da ronda."
    },
    "hostname": {
      "type": "string",
      "format": "hostname",
      "description": "Alvo normalizado — é por ele que a cota de apps é contada."
    },
    "target": {
      "type": "string",
      "format": "uri",
      "description": "URL exata que você mandou escanear."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "analyzing",
        "done",
        "failed",
        "canceled"
      ],
      "description": "Estado atual."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Quando a ronda foi criada."
    },
    "finished_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Quando terminou. `null` enquanto roda."
    },
    "progress": {
      "oneOf": [
        {
          "$ref": "#/$defs/ScanProgress"
        },
        {
          "type": "null"
        }
      ],
      "description": "Onde a ronda está enquanto roda — a mesma leitura da tela de espera. `null` quando não está rodando (ainda na fila, terminada, falha ou cancelada)."
    },
    "summary": {
      "oneOf": [
        {
          "$ref": "#/$defs/ScanSummary"
        },
        {
          "type": "null"
        }
      ],
      "description": "Resumo do resultado. `null` enquanto a ronda não produziu resultado (`queued`, `running`, `analyzing`) e numa ronda `failed` que morreu antes de gerar algo."
    }
  },
  "required": [
    "id",
    "hostname",
    "target",
    "status",
    "created_at",
    "finished_at",
    "progress",
    "summary"
  ],
  "$defs": {
    "ScanProgress": {
      "type": "object",
      "properties": {
        "phase": {
          "type": "string",
          "enum": [
            "running",
            "analyzing"
          ],
          "description": "`running` = rodando as verificações · `analyzing` = na análise com IA."
        },
        "done": {
          "type": "integer",
          "minimum": 0,
          "description": "Verificações concluídas (fase `running`)."
        },
        "total": {
          "type": "integer",
          "minimum": 0,
          "description": "Verificações previstas nesta ronda."
        },
        "module": {
          "type": [
            "string",
            "null"
          ],
          "description": "Verificação em andamento (`headers`, `cors`, `supabase`…). `null` quando nenhuma está em andamento."
        },
        "with_ai": {
          "type": "boolean",
          "description": "A análise com IA vem depois das verificações (define quantas etapas faltam)."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "Última atualização do progresso — string ISO 8601 em UTC (`2026-08-27T14:09:24.106Z`)."
        }
      },
      "description": "Progresso de uma ronda em execução — o mesmo que a tela de espera mostra. Só existe enquanto a ronda roda.",
      "required": [
        "phase",
        "done",
        "total",
        "module",
        "with_ai",
        "updated_at"
      ]
    },
    "ScanSummary": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Id da ronda."
        },
        "target": {
          "type": "string",
          "format": "uri",
          "description": "URL exata que foi escaneada."
        },
        "hostname": {
          "type": "string",
          "format": "hostname",
          "description": "Forma normalizada do alvo."
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "running",
            "analyzing",
            "done",
            "failed",
            "canceled"
          ],
          "description": "Estado da ronda."
        },
        "score": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "Exposição de 0 a 100 (maior = pior)."
        },
        "riskLabel": {
          "type": "string",
          "enum": [
            "SECURE",
            "LOW_RISK",
            "MODERATE_RISK",
            "HIGH_RISK",
            "CRITICAL_RISK"
          ],
          "description": "Faixa do score."
        },
        "criticalCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Achados `critical`."
        },
        "finishedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Quando terminou."
        },
        "durationMs": {
          "type": "integer",
          "minimum": 0,
          "description": "Duração da ronda, em milissegundos."
        },
        "blocked": {
          "type": "boolean",
          "description": "A ronda não viu o app. Ausente = `false`."
        },
        "blockedReason": {
          "type": "string",
          "enum": [
            "connection",
            "challenge"
          ],
          "description": "Só com `blocked`. `connection` = não alcançamos o app a partir dos nossos servidores (problema do nosso lado; nada a liberar). `challenge` = o app respondeu com desafio ou 403 de WAF/anti-bot (aí vale liberar a Guarita no seu provedor)."
        }
      },
      "description": "Resumo derivado do relatório. Formato do scanner (`camelCase`), entregue como ele é.",
      "required": [
        "id",
        "target",
        "hostname",
        "status",
        "score",
        "riskLabel",
        "criticalCount",
        "durationMs"
      ]
    }
  }
}