Findings API

Gestione hallazgos de vulnerabilidades descubiertos durante escaneos.

Endpoints

Método	Endpoint	Descripción
GET	/api/v1/findings	Listar todos los hallazgos
GET	/api/v1/findings/{id}	Obtener detalles de hallazgo
PATCH	/api/v1/findings/{id}	Actualizar estado de hallazgo
POST	/api/v1/findings/{id}/comments	Agregar comentario
GET	/api/v1/findings/stats	Obtener estadísticas de hallazgos

Listar Hallazgos

Recupere todos los hallazgos de vulnerabilidades.

GET /api/v1/findings

Parámetros de Consulta

Parámetro	Tipo	Descripción
page	integer	Número de página (predeterminado: 1)
per_page	integer	Elementos por página (predeterminado: 20, máx: 100)
severity	string	Filtrar: critical, high, medium, low, info
status	string	Filtrar: open, in_progress, resolved, false_positive, accepted
scan_id	string	Filtrar por escaneo
target	string	Filtrar por dominio objetivo
tool	string	Filtrar por herramienta de detección
cve	string	Filtrar por ID de CVE
sort	string	Ordenar por: severity, created_at, cvss_score
order	string	Orden: asc, desc

Respuesta

{
  "items": [
    {
      "id": "finding_abc123",
      "title": "Remote Code Execution via Deserialization",
      "severity": "critical",
      "status": "open",
      "cvss_score": 9.8,
      "epss_score": 0.85,
      "target": "example.com",
      "affected_component": "https://example.com/api/upload",
      "tool": "nuclei",
      "template_id": "CVE-2024-1234",
      "cve_ids": ["CVE-2024-1234"],
      "cwe_ids": ["CWE-502"],
      "scan_id": "scan_xyz789",
      "detected_at": "2025-12-21T10:30:00Z",
      "frameworks": ["SOC 2", "PCI-DSS"]
    }
  ],
  "total": 156,
  "page": 1,
  "per_page": 20,
  "pages": 8
}

Obtener Detalles de Hallazgo

Recupere detalles completos de un hallazgo.

GET /api/v1/findings/{finding_id}

Respuesta

{
  "id": "finding_abc123",
  "title": "Remote Code Execution via Deserialization",
  "severity": "critical",
  "status": "open",
  "cvss_score": 9.8,
  "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
  "epss_score": 0.85,
  "target": "example.com",
  "affected_component": "https://example.com/api/upload",
  "description": "The application deserializes untrusted data without validation, allowing remote code execution...",
  "impact": "An attacker can execute arbitrary code on the server, potentially gaining full system access...",
  "remediation": {
    "summary": "Avoid deserializing untrusted data. If necessary, use allowlists for permitted classes.",
    "steps": [
      "Update the serialization library to the latest version",
      "Implement input validation before deserialization",
      "Use secure deserialization patterns"
    ],
    "code_example": "// Example secure deserialization...",
    "references": [
      "https://owasp.org/www-project-web-security-testing-guide/"
    ]
  },
  "evidence": {
    "request": "POST /api/upload HTTP/1.1...",
    "response": "HTTP/1.1 500 Internal Server Error...",
    "screenshot_url": null
  },
  "tool": "nuclei",
  "template_id": "CVE-2024-1234",
  "cve_ids": ["CVE-2024-1234"],
  "cwe_ids": ["CWE-502"],
  "scan_id": "scan_xyz789",
  "detected_at": "2025-12-21T10:30:00Z",
  "frameworks": [
    {
      "name": "SOC 2",
      "controls": ["CC6.1", "CC7.1"]
    },
    {
      "name": "PCI-DSS",
      "controls": ["6.5.1", "11.3"]
    }
  ],
  "comments": [
    {
      "id": "comment_123",
      "user": "[email protected]",
      "text": "Assigned to security team for immediate review",
      "created_at": "2025-12-21T11:00:00Z"
    }
  ],
  "history": [
    {
      "action": "status_changed",
      "from": null,
      "to": "open",
      "user": "system",
      "timestamp": "2025-12-21T10:30:00Z"
    }
  ]
}

Actualizar Hallazgo

Actualice el estado o propiedades de un hallazgo.

PATCH /api/v1/findings/{finding_id}
Content-Type: application/json

Cuerpo de Solicitud

{
  "status": "in_progress",
  "assignee": "[email protected]",
  "priority": "high",
  "due_date": "2025-12-28T00:00:00Z",
  "notes": "Escalated to development team"
}

Valores de Estado Válidos

Estado	Descripción
open	Hallazgo sin atender
in_progress	Remediación en curso
resolved	Hallazgo ha sido corregido
false_positive	No es un hallazgo válido
accepted	Riesgo aceptado, sin remediación planeada

Respuesta

{
  "id": "finding_abc123",
  "status": "in_progress",
  "assignee": "[email protected]",
  "updated_at": "2025-12-21T12:00:00Z"
}

Agregar Comentario

Agregue un comentario a un hallazgo.

POST /api/v1/findings/{finding_id}/comments
Content-Type: application/json

Cuerpo de Solicitud

{
  "text": "Verified the vulnerability. Working on patch."
}

Respuesta

{
  "id": "comment_456",
  "finding_id": "finding_abc123",
  "user": "[email protected]",
  "text": "Verified the vulnerability. Working on patch.",
  "created_at": "2025-12-21T12:30:00Z"
}

Estadísticas de Hallazgos

Obtenga estadísticas agregadas de hallazgos.

GET /api/v1/findings/stats

Parámetros de Consulta

Parámetro	Tipo	Descripción
from_date	string	Fecha de inicio (ISO 8601)
to_date	string	Fecha de fin (ISO 8601)
target	string	Filtrar por objetivo

Respuesta

{
  "total": 156,
  "by_severity": {
    "critical": 5,
    "high": 23,
    "medium": 67,
    "low": 45,
    "info": 16
  },
  "by_status": {
    "open": 89,
    "in_progress": 34,
    "resolved": 28,
    "false_positive": 3,
    "accepted": 2
  },
  "by_tool": {
    "nuclei": 89,
    "sqlmap": 12,
    "semgrep": 34,
    "trivy": 21
  },
  "trends": {
    "new_this_week": 23,
    "resolved_this_week": 18,
    "average_resolution_days": 7.5
  }
}

Operaciones en Lote

Actualización Masiva de Estado

POST /api/v1/findings/bulk
Content-Type: application/json

{
  "finding_ids": ["finding_123", "finding_456", "finding_789"],
  "update": {
    "status": "false_positive",
    "notes": "Verified not exploitable in this context"
  }
}

Exportar Hallazgos

GET /api/v1/findings/export?format=csv

Formatos soportados: csv, json, pdf

Análisis AI

Todos los Planes

Análisis impulsado por IA disponible en todos los planes (se aplican límites de cuota).

Obtenga orientación de remediación generada por IA:

GET /api/v1/findings/{finding_id}/ai-analysis

Respuesta

{
  "finding_id": "finding_abc123",
  "ai_analysis": {
    "risk_assessment": "This vulnerability poses critical risk due to...",
    "attack_scenarios": [
      "An attacker could exploit this by...",
      "Combined with other findings, this enables..."
    ],
    "remediation_priority": "immediate",
    "recommended_actions": [
      "Apply the latest security patch",
      "Implement WAF rules to block exploit attempts",
      "Enable monitoring for suspicious activity"
    ],
    "automation_available": true,
    "ansible_playbook_id": "playbook_remediate_rce"
  },
  "ai_credits_used": 1
}