Reports

Reports are generated from completed scans and include severity breakdowns, correlated intelligence, and remediation recommendations.

Generating Reports

Reports are generated on-demand via the report endpoint. The scan must have a status of "completed" or "running" to generate a report. Scans with "pending", "failed", or "cancelled" status return a 400 error.

GET /api/v1/scans/{id}/report

curl https://api.xnolex.com/api/v1/scans/{scan_id}/report \
  -H "Authorization: Bearer <token>"

Report Structure

The report is a structured JSON object containing the following sections:

Metadata

Scan identification and timing information.

Metadata section

{
  "report_type": "structured_scan_report",
  "generated_at": "2025-01-15T10:30:00Z",
  "scan_metadata": {
    "scan_id": "550e8400-...",
    "target_domain": "example.com",
    "engine": "full",
    "status": "completed",
    "started_at": "2025-01-15T10:00:00Z",
    "completed_at": "2025-01-15T10:28:00Z",
    "created_at": "2025-01-15T09:59:00Z"
  }
}

Summary

Aggregate counts of findings, subdomains, and endpoints.

Summary section

{
  "summary": {
    "total_findings": 12,
    "severity_breakdown": {
      "critical": 2,
      "high": 3,
      "medium": 4,
      "low": 2,
      "info": 1
    },
    "total_subdomains": 15,
    "total_endpoints": 8
  },
  "severity_summary": {
    "Critical": 2,
    "High": 3,
    "Medium": 4,
    "Low": 2,
    "Informational": 1
  }
}

Data Collections

The report includes full lists of subdomains, endpoints, and vulnerabilities discovered during the scan.

Recommendations

Reports include auto-generated recommendations based on the severity of discovered findings:

Critical > 0: "URGENT: Address all critical vulnerabilities immediately."

High > 0: "High priority: Remediate high-severity findings before next release."

Medium > 0: "Plan remediation for medium-severity findings within the next sprint."

Low > 0: "Low-severity findings should be addressed during regular maintenance."

No vulnerabilities: "No vulnerabilities were detected. Maintain current security posture."

Note

Recommendations are generated based on the presence of findings at each severity level, not the count. A single critical finding triggers the urgent recommendation.

Correlated Intelligence

The report includes a correlated_intel section that maps vulnerabilities to their affected hosts and analyzes the attack surface.

Host-Vulnerability Map

Groups vulnerabilities by affected host, showing the count and list of findings for each.

Host-vulnerability mapping

"host_vulnerability_map": {
  "api.example.com": {
    "count": 3,
    "findings": [
      {"name": "Apache Struts RCE", "severity": "critical"},
      {"name": "CORS Misconfiguration", "severity": "medium"},
      {"name": "Missing Security Headers", "severity": "low"}
    ]
  },
  "app.example.com": {
    "count": 1,
    "findings": [
      {"name": "XSS in Search", "severity": "high"}
    ]
  }
}

Attack Surface Analysis

Categorizes discovered endpoints to provide insight into the attack surface:

Attack surface data

"attack_surface": {
  "total_subdomains": 15,
  "total_endpoints": 8,
  "critical_paths": 5,
  "auth_endpoints": 2,
  "admin_endpoints": 1,
  "api_endpoints": 3
}

critical_paths: Endpoints returning 200, 301, or 302 status codes (live, accessible paths).

auth_endpoints: Endpoints with "auth" or "login" in the URL.

admin_endpoints: Endpoints with "admin" in the URL.

api_endpoints: Endpoints with "/api/" in the URL.

Planned Features

Info

GPT-powered narrative reports and PDF export are listed as planned features on the roadmap. They are not currently implemented. The current report format is structured JSON designed for programmatic consumption and custom rendering.