Session Data

Every scan run produces a timestamped session directory containing structured results, raw per-module output, the pipeline log, and the generated report. session_results.json is the master artifact; every downstream tool (report generator, diff, upload, scoring) reads it.

Session Directory Structure

Sessions are stored under $HOME/netvuln-tool/sessions/<timestamp>/, where the timestamp is YYYYMMDD_HHMMSS:

sessions/20260718_120000/
├── session_results.json    # Master structured findings (JSON)
├── pipeline.log            # Per-session execution log
├── dns_enumeration.txt     # Raw DNS output
├── port_enumeration.txt    # Raw nmap port-scan output
├── smb_enumeration.txt     # Raw SMB output
├── snmp_enumeration.txt    # Raw SNMP output
├── vuln_assessment.txt     # Raw vulnerability-scan output
├── *.xml                   # nmap -oX XML (parsed by the Python orchestrator)
└── report_20260718_121500.html

Session JSON Schema

The initial document is created by the orchestrator with metadata, hosts, findings, timing, and summary; the Bash modules and report phase enrich it in place (adding dns, remediation, compliance, topology, and scoring fields). A representative shape:

{
  "metadata": {
    "session_id": "20260718_120000",
    "target": "192.168.1.0/24",
    "start_time": "2026-07-18T12:00:00Z",
    "end_time": "2026-07-18T12:15:00Z",
    "tool_version": "4.2.4",
    "assessor": "",
    "client": "acme-corp",
    "scope": "192.168.1.0/24",
    "phases_executed": ["discovery", "enumeration", "vuln", "report"],
    "license": { "tier": "msp", "fingerprint": "…", "source": "config:NV_API_KEY", "validated_at": "…" }
  },
  "hosts": [
    {
      "ip": "192.168.1.10",
      "hostname": "web01",
      "os_guess": "Linux 5.x",
      "status": "up",
      "mac_address": "aa:bb:cc:dd:ee:ff",
      "ports": [
        { "port": 443, "protocol": "tcp", "state": "open", "service": "https", "version": "nginx 1.24.0" }
      ]
    }
  ],
  "findings": [
    { "id": "F001", "severity": "critical", "host": "192.168.1.10", "port": 443,
      "title": "…", "description": "…", "cve": ["CVE-2021-44228"] }
  ],
  "dns": { "example.com": { "A": ["…"], "MX": ["…"], "DMARC": "…", "SPF": "…" } },
  "timing": { "discover_hosts": 12, "enum_ports": 34, "total": 128.4 },
  "summary": {
    "total_hosts": 3,
    "hosts_up": 3,
    "total_ports_open": 9,
    "total_findings": 6,
    "by_severity": { "critical": 1, "high": 1, "medium": 2, "low": 1, "info": 1 },
    "risk_score": 47,
    "risk_grade": "C",
    "risk_score_operational": 32,
    "risk_grade_operational": "B",
    "exception_impact": { "excepted_count": 1, "score_delta": 15, "excepted_findings": {} }
  }
}

Top-Level Keys

• metadata: session id, target, start/end times, tool version, assessor, client id, scope, executed phases, and a license fingerprint block (tier, sha256 fingerprint prefix, source, validation time). The plaintext key is never stored.
• hosts: per host: IP, hostname, OS guess, status, optional MAC address and hop distance, and open ports with protocol, state, service, and version.
• findings: deduplicated and re-numbered (F001, F002, …), sorted by severity, each with affected host, port, description, and CVE references where applicable.
• dns: full DNS records per domain (A, AAAA, MX, NS, TXT, SOA, CNAME, PTR, SRV, CAA, DMARC, SPF).
• timing: per-module and per-phase runtime plus a total, used for the report's timing grid.
• summary: host/port/finding counts, by_severity breakdown, and the dual scoring output (base risk_score/risk_grade and operational risk_score_operational/risk_grade_operational with exception_impact). See Scoring Methodology.
• remediation: status of each finding across sessions (new, persistent, resolved, deferred) with notes and exception metadata.
• compliance: findings mapped to CIS Controls v8, NIST CSF, PCI-DSS v4.0, SOC 2, and ORC 9.64. See Compliance Mapping.
• topology: network-topology data with subnet grouping and per-host risk grades.

The full field-by-field contract shared with the portal is documented in the API Contract.

Aggregation and Scoring

The report phase calls aggregate_results, which:

1. Deduplicates findings by (host, port, title), keeping the first.
2. Re-numbers IDs as F001, F002, …
3. Sorts by severity (critical → info).
4. Rebuilds summary with host/port/finding counts and the by_severity map.
5. Computes the base and operational risk scores.

Logging

Multiple logs are maintained at different scopes:

Log File	Location	Purpose
Main log	$HOME/netvuln-tool/logs/vulnscan.log	Global application log
Session log	$HOME/netvuln-tool/sessions/<timestamp>/pipeline.log	Per-session execution log
Scan results	$HOME/netvuln-tool/logs/scan_results.log	Scan-result history

The session log is embedded in the HTML report as a searchable, collapsible section; when expanded it is included in PDF/print exports. All log files and session directories are created with secure permissions (600 for files, 700 for directories).

Related

• Report Template: how this JSON becomes an HTML report.
• Python Orchestrator: nmap XML parsing and native scoring over the same schema.
• Session Management: uploading, pushing, and diffing sessions.