Security Scanner Integration Tool

Build a Python command-line tool that integrates with a dependency vulnerability scanner to generate comprehensive security reports that include announcements, warnings, and scan results.

Overview

Your tool should scan Python dependencies for vulnerabilities and capture all security announcements, notifications, and warnings that the scanner provides. The output should be parsed and formatted into a structured report that security teams can review.

Requirements

Core Functionality

The tool must perform the following:

1. Execute Vulnerability Scan: Run a dependency vulnerability scan on a given requirements file or project directory.

2. Capture Announcements: Extract any security announcements or platform notifications returned by the scanner.

3. Capture Local Warnings: Identify and collect local warnings such as:

   • Unpinned requirements warnings
   • Invalid version format warnings
   • Other scan-related warnings

4. Generate Report: Create a structured JSON report containing:

   • Total number of announcements received
   • List of announcement messages with their types
   • Total number of local warnings
   • List of warning messages with their categories
   • Scan status (success/failure)
   • Timestamp of the scan

Implementation Details

• Your tool should accept a command-line argument for the target path to scan
• Use JSON output format for machine-readable results
• Handle cases where no announcements or warnings are present
• Properly categorize different types of notifications (announcements vs. warnings)

Output Format

The tool should output a JSON structure like:

{
  "scan_timestamp": "2025-12-31T17:45:00Z",
  "scan_status": "completed",
  "announcements": {
    "count": 2,
    "items": [
      {
        "type": "security",
        "message": "New vulnerability database available"
      }
    ]
  },
  "warnings": {
    "count": 3,
    "items": [
      {
        "category": "unpinned_requirements",
        "message": "Package 'requests' is not pinned to a specific version"
      }
    ]
  }
}

Test Cases

• Given a requirements file with pinned versions, the tool runs a scan and reports zero unpinned warnings @test
• Given a requirements file with unpinned versions (e.g., "requests" without version), the tool detects and reports unpinned requirement warnings @test
• Given a valid project directory, the tool successfully captures any security announcements from the platform @test
• Given scan output with both announcements and warnings, the tool correctly categorizes and counts each type @test

Implementation

@generates

API

def run_scan(target_path: str) -> dict:
    """
    Execute a vulnerability scan and capture all announcements and warnings.

    Args:
        target_path: Path to requirements file or project directory to scan

    Returns:
        dict: Structured report containing scan results, announcements, and warnings

    Raises:
        ValueError: If target_path does not exist
        RuntimeError: If scan execution fails
    """
    pass

def parse_scan_output(scan_output: str) -> dict:
    """
    Parse scanner output to extract announcements and warnings.

    Args:
        scan_output: Raw output from the vulnerability scanner

    Returns:
        dict: Parsed announcements and warnings with counts and categorization
    """
    pass

def generate_report(scan_data: dict) -> str:
    """
    Generate a formatted JSON report from scan data.

    Args:
        scan_data: Dictionary containing scan results, announcements, and warnings

    Returns:
        str: JSON-formatted report string
    """
    pass

Dependencies { .dependencies }

safety { .dependency }

Provides dependency vulnerability scanning with announcements and notification capabilities.

@satisfied-by