python-packaging-binary-audit

Python Packaging Binary Audit

Scans a Python package repository for compiled or binary files using Fromager-style extension and magic-header detection, then runs malcontent YARA-based analysis on any detected binaries. Produces a self-contained "Binary Scan" report section with triaged findings and a risk assessment.

Inputs

• repo_path (required): Local filesystem path to an already-cloned repository
• output_file (optional): Write the report section to this file path instead of returning it inline. The first line of the file must be RISK_RATING:<value> so the orchestrator can parse it without reading the full report.
• binary_scan (optional): File path to pre-computed binary scanner JSON output (binary-scan.json). Schema: {total, findings[{path, match_type, suffix, size, magic?}]}. When provided, skip running scan_binaries.py.
• malcontent_results (optional): File path to pre-computed malcontent JSON output (malcontent-results.json). Schema: {status, Files?}. Status values: "success", "unavailable", "timeout", "failed", "invalid", "skipped". When provided, skip running run_malcontent.py.

Step 1: Obtain Binary Scan Results

Option A - Pre-computed results (CI mode)

If binary_scan is provided and the file exists, read and parse it as JSON. Use the total and findings fields directly. Skip running scan_binaries.py and skip creating the staging directory (STAGING_DIR) since binaries are already analyzed. Each finding has: path (relative to repo root), match_type ("extension" or "magic_header"), suffix, size, and optionally magic (ELF, MachO, ar_archive, etc.).

If total is 0, skip to the Output section and note "No binary files detected" in the report.

Option B - Run binary scanner locally (standalone mode)

If binary_scan is not provided, run the binary scanner to find compiled files using Fromager-style extension and magic-header detection:

STAGING_DIR=$(mktemp -d -t malcontent-staging-XXXXXX)
./scripts/scan_binaries.py --stage-to "$STAGING_DIR" "<repo-path>"