PGDN Reporter

A focused security scoring and assessment library extracted from the PGDN network security scanning system.

Overview

PGDN Reporter provides security scoring and risk assessment capabilities for network security scan data. It's designed to be lightweight, extensible, and focused solely on the scoring logic without database dependencies or complex agent systems.

Features

• Security Scoring: Calculate risk scores (0-10) based on vulnerability severity and network exposure
• Risk Assessment: Determine overall risk levels (LOW, MEDIUM, HIGH, CRITICAL)
• Actionable Recommendations: Generate security recommendations based on scan results
• JSON-Only CLI: Clean command-line interface with JSON input/output
• No External Dependencies: Core library has zero external dependencies
• Extensible: Easy to customize scoring weights and risk calculations

Installation

# Install the library
pip install -e .

# For development with optional dependencies
pip install -e .[dev]

Usage

Command Line Interface

The CLI accepts JSON input and returns JSON output:

# Score from stdin
echo '{"target": "127.0.0.1", "vulnerabilities": [...]}' | pgdn-reporter score

# Score from file
pgdn-reporter score -i scan_results.json

# Pretty print output
pgdn-reporter score -i scan_results.json --pretty

Python Library

from pgdn_reporter import SecurityScorer, ScanData, VulnerabilityData, Severity

# Create scan data
scan_data = ScanData(
    target="127.0.0.1",
    vulnerabilities=[
        VulnerabilityData(
            id="CVE-2023-1234",
            severity=Severity.HIGH,
            title="SQL Injection",
            ports=[3306]
        )
    ],
    open_ports=[22, 80, 443, 3306]
)

# Generate security report
scorer = SecurityScorer()
report = scorer.generate_report(scan_data)

print(f"Risk Score: {report.risk_score}/10")
print(f"Risk Level: {report.risk_level.value}")
print(f"Recommendations: {report.recommendations}")

Data Format

Input JSON Structure

{
  "target": "127.0.0.1",
  "scan_timestamp": "2023-01-01T00:00:00Z",
  "vulnerabilities": [
    {
      "id": "CVE-2023-1234",
      "severity": "HIGH",
      "title": "SQL Injection Vulnerability",
      "description": "SQL injection in web application",
      "cve_id": "CVE-2023-1234",
      "cvss_score": 7.5,
      "ports": [3306],
      "services": ["mysql"],
      "references": ["https://cve.mitre.org/..."]
    }
  ],
  "open_ports": [22, 80, 443, 3306],
  "services": {
    "22": "ssh",
    "80": "http",
    "443": "https",
    "3306": "mysql"
  },
  "metadata": {}
}

Output JSON Structure

{
  "target": "127.0.0.1",
  "risk_score": 7.0,
  "risk_level": "HIGH",
  "total_vulnerabilities": 1,
  "severity_breakdown": {
    "CRITICAL": 0,
    "HIGH": 1,
    "MEDIUM": 0,
    "LOW": 0
  },
  "high_risk_ports": [3306],
  "recommendations": [
    "Prioritize fixing 1 high-severity vulnerabilities",
    "Review exposure of high-risk ports: 3306"
  ],
  "scan_timestamp": "2023-01-01T00:00:00Z",
  "metadata": {}
}

Customization

from pgdn_reporter import SecurityScorer, Severity

# Custom severity weights
custom_weights = {
    Severity.CRITICAL: 15.0,  # Higher weight for critical
    Severity.HIGH: 8.0,
    Severity.MEDIUM: 3.0,
    Severity.LOW: 0.5
}

# Custom high-risk ports
custom_ports = {21, 23, 135, 445, 1433, 3306, 5432}

# Initialize with custom configuration
scorer = SecurityScorer(
    severity_weights=custom_weights,
    high_risk_ports=custom_ports,
    port_risk_multiplier=3.0
)

License

MIT License - see LICENSE file for details.