<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Vulnerability Report Generators — API Reference

## Scanner Output Formats

### Nuclei JSON Lines
```json
{"template-id": "cve-2021-44228", "info": {"name": "Log4Shell", "severity": "critical", "classification": {"cvss-score": 10.0, "cve-id": ["CVE-2021-44228"]}}, "host": "https://target.com", "matched-at": "https://target.com/api"}
```

### Semgrep JSON
```json
{"results": [{"check_id": "python.lang.security.audit.eval-usage", "path": "app.py", "start": {"line": 42}, "extra": {"severity": "WARNING", "message": "Use of eval()", "metadata": {"cwe": ["CWE-95"]}}}]}
```

### Nmap XML
```xml
<nmaprun>
  <host><address addr="192.168.1.1"/>
    <ports><port protocol="tcp" portid="80">
      <state state="open"/><service name="http" product="Apache"/>
    </port></ports>
  </host>
</nmaprun>
```

## CVSS v3.1 Scoring

| Score Range | Severity |
|-------------|----------|
| 0.0 | None |
| 0.1–3.9 | Low |
| 4.0–6.9 | Medium |
| 7.0–8.9 | High |
| 9.0–10.0 | Critical |

```python
def cvss_to_severity(score: float) -> str:
    if score >= 9.0: return "critical"
    if score >= 7.0: return "high"
    if score >= 4.0: return "medium"
    if score > 0.0: return "low"
    return "info"
```

## Report Templates

### Jinja2 HTML Template
```python
from jinja2 import Template

TEMPLATE = """
<html><body>
<h1>Vulnerability Report</h1>
<table>
<tr><th>Severity</th><th>Title</th><th>Host</th><th>CVSS</th></tr>
{% for f in findings %}
<tr><td>{{ f.severity }}</td><td>{{ f.title }}</td><td>{{ f.affected_host }}</td><td>{{ f.cvss }}</td></tr>
{% endfor %}
</table>
</body></html>
"""

html = Template(TEMPLATE).render(findings=findings)
```

## CLI Tools for Parsing

```bash
# Parse Nuclei JSONL
cat nuclei-results.jsonl | jq -r '[.info.severity, .info.name, .host] | @tsv'

# Parse Semgrep JSON
cat semgrep.json | jq -r '.results[] | [.extra.severity, .check_id, .path, .start.line] | @tsv'

# Parse Nmap XML
xmlstarlet sel -t -m "//port[state/@state='open']" -v "../address/@addr" -o ":" -v "@portid" -n results.xml
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Report generated successfully |
| 1 | Critical/high findings present |
| 2 | Parse error or invalid input |
