Package Security Audit Tool

A comprehensive security audit tool for macOS developer machines. Scans all installed software, detects vulnerabilities, and provides Claude-powered mitigation recommendations.

Features

• Full System Inventory — Collects all installed packages and applications
• CVE Scanning — Queries OSV.dev for known vulnerabilities
• Intelligent Prioritization — Highlights high-severity issues first
• Claude Analysis — AI-powered mitigation strategies for each vulnerability
• Multiple Reports — JSON for processing, HTML for human review

Architecture

collect-inventory.sh  →  audit tool  →  Claude analysis  →  Reports (JSON + HTML)

Components

1. Inventory Script (scripts/collect-inventory.sh)

   • Scans Homebrew, pip, npm, Go, Rust packages
   • Extracts application metadata from /Applications
   • Outputs structured JSON inventory

2. Audit Tool (cmd/audit)

   • Parses inventory
   • Queries OSV.dev for CVEs
   • Filters by severity
   • Coordinates Claude analysis

3. Claude Integration

   • CLI mode: Uses claude command (Claude Code)
   • SDK mode: Uses Anthropic SDK (requires ANTHROPIC_API_KEY)
   • Generates per-CVE recommendations

4. Report Generation

   • JSON output for programmatic use
   • HTML fallback (or Astro 7 static site)

Installation

Prerequisites

• Go 1.22+
• macOS 11+
• Homebrew (optional, for easy installation)

Setup

# Clone/enter repository
cd ~/Projects/package-review

# Download dependencies
go mod download

# Build the tool
go build -o bin/audit ./cmd/audit

Usage

Step 1: Collect System Inventory

./scripts/collect-inventory.sh
# Output: inventory.json

Step 2: Run Security Audit

Option A: Using Claude Code CLI (default)

go run ./cmd/audit

Option B: Using Anthropic SDK

export ANTHROPIC_API_KEY=sk-...
go run ./cmd/audit -claude=sdk

Step 3: Review Reports

# JSON report (for processing/CI/CD)
cat audit_report.json | jq '.summary'

# HTML report (for human review)
open audit_report.html

Configuration

CLI Flags

-inventory string     Path to inventory JSON (default "inventory.json")
-json string          Output audit report as JSON (default "audit_report.json")
-html string          Output audit report as HTML (default "audit_report.html")
-claude string        Claude integration: 'claude' (CLI) or 'sdk' (Anthropic SDK)

Example

./scripts/collect-inventory.sh /tmp/my-inventory.json
go run ./cmd/audit \
  -inventory=/tmp/my-inventory.json \
  -json=/tmp/audit.json \
  -html=/tmp/audit.html \
  -claude=sdk

Output

JSON Report Structure

{
  "timestamp": "2026-06-23T15:30:00Z",
  "system": { "os": "Darwin", "macos_version": "14.5", ... },
  "summary": {
    "total_packages": 150,
    "vulnerable_count": 23,
    "high_severity": 8,
    "critical_findings": 1
  },
  "findings": [
    {
      "package_name": "curl",
      "package_version": "7.68.0",
      "cve_id": "CVE-2021-22911",
      "cvss_score": 7.5,
      "severity": "HIGH",
      "summary": "...",
      "link": "https://..."
    }
  ],
  "mitigations": [
    {
      "finding": { /* ... */ },
      "recommendation": "update",
      "rationale": "...",
      "next_steps": "..."
    }
  ]
}

HTML Report

Interactive report with:

• Summary metrics (total packages, vulnerabilities by severity)
• Sortable/filterable findings table
• Per-finding mitigation recommendations
• Direct links to CVE advisories

Workflow Examples

One-time Audit

./scripts/collect-inventory.sh
go run ./cmd/audit
open audit_report.html

Scheduled Audits (cron)

#!/bin/bash
cd ~/Projects/package-review
./scripts/collect-inventory.sh audit-$(date +%Y-%m-%d).json
go run ./cmd/audit -inventory=audit-$(date +%Y-%m-%d).json
# Send report via email, Slack, etc.

CI/CD Integration

# GitHub Actions example
- name: Run security audit
  run: |
    ./scripts/collect-inventory.sh
    go run ./cmd/audit
    
- name: Check for critical findings
  run: |
    CRITICAL=$(jq '.summary.critical_findings' audit_report.json)
    if [ "$CRITICAL" -gt 0 ]; then
      echo "Critical vulnerabilities found!"
      exit 1
    fi

Data Sources

CVE Database: OSV.dev

• Coverage: 24+ open-source ecosystems
• Latency: 1.8 days (fastest)
• Rate Limit: Unlimited
• Authentication: None required
• URL: https://api.osv.dev

Package Ecosystems Supported

Source	Coverage
Homebrew	✅ Full (via formulae.brew.sh)
Python (pip)	✅ Full (PyPI)
Node.js (npm)	✅ Full
Go	✅ Full
Rust (Cargo)	✅ Full
Applications	⚠️ Limited (VirusTotal in Phase 2)

Limitations

Current (MVP)

• Homebrew packages: Limited CVE coverage (via OSV.dev's GIT ecosystem)
• Applications: No vulnerability database integration (planned Phase 2)
• System software: No automated Apple security update checking

Planned (Phase 2)

• Third-party app scanning (Chrome, Slack, VS Code, etc.)
• VirusTotal integration for malware detection
• Application version detection improvement
• Historical trend tracking

Troubleshooting

"Inventory file not found"

# Make sure inventory script ran successfully
./scripts/collect-inventory.sh
ls -lh inventory.json

"Error scanning OSV.dev"

# Check network connectivity
curl https://api.osv.dev/v1/query
# Check JSON query format
cat inventory.json | jq '.' | head -20

"Claude command not found" (CLI mode)

# Install Claude Code
brew install anthropic/claude/claude

# Or use SDK mode instead
export ANTHROPIC_API_KEY=sk-...
go run ./cmd/audit -claude=sdk

No findings returned

• Packages might not be in OSV.dev
• Version format might not match
• Check individual OSV.dev query:

  curl -X POST https://api.osv.dev/v1/query \
    -H "Content-Type: application/json" \
    -d '{"package":{"name":"curl","ecosystem":"PyPI"},"version":"7.68.0"}'
  

Development

Project Structure

.
├── cmd/audit/              # CLI entry point
├── internal/
│   ├── inventory/          # Inventory parsing
│   ├── security/           # CVE scanning & Claude integration
│   └── report/             # Report generation
├── scripts/
│   └── collect-inventory.sh # System inventory collection
└── web/                    # Astro 7 static site (Phase 2)

Building from Source

go build -o bin/audit ./cmd/audit
./bin/audit

Testing

# Run unit tests (when added)
go test ./...

# Integration test with sample inventory
./scripts/collect-inventory.sh test-inventory.json
go run ./cmd/audit -inventory=test-inventory.json

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT

Security

This tool analyzes security vulnerabilities but does not replace:

• Professional security audits
• Vulnerability management policies
• Incident response procedures

Always verify findings and implement mitigations carefully.

Support

For issues, questions, or suggestions:

1. Check DATA_SOURCES_SPEC.md for detailed source documentation
2. Review error messages in the HTML report
3. Check Claude's mitigation recommendations

---

Version: 1.0.0-alpha
Status: MVP (Homebrew + package managers)
Phase 2: Third-party applications scanning