macos-package-review/README.md

# 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

```bash
# 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

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

### Step 2: Run Security Audit

**Option A: Using Claude Code CLI** (default)
```bash
go run ./cmd/audit
```

**Option B: Using Anthropic SDK**
```bash
export ANTHROPIC_API_KEY=sk-...
go run ./cmd/audit -claude=sdk
```

### Step 3: Review Reports

```bash
# 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

```bash
./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

```json
{
  "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
```bash
./scripts/collect-inventory.sh
go run ./cmd/audit
open audit_report.html
```

### Scheduled Audits (cron)
```bash
#!/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
```yaml
# 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"
```bash
# Make sure inventory script ran successfully
./scripts/collect-inventory.sh
ls -lh inventory.json
```

### "Error scanning OSV.dev"
```bash
# 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)
```bash
# 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: 
  ```bash
  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
```bash
go build -o bin/audit ./cmd/audit
./bin/audit
```

### Testing
```bash
# 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