Initial project scaffold: macOS package security audit tool

This commit establishes the foundation for a comprehensive security audit
tool for macOS developer machines. It audits all installed software,
detects vulnerabilities via OSV.dev, and provides Claude-powered
mitigation recommendations.

## Architecture

- System inventory collection (Homebrew, pip, npm, Go, Rust, apps)
- CVE scanning via OSV.dev API (no auth, unlimited rate limits)
- Claude integration (CLI or SDK) for mitigation analysis
- JSON + HTML report generation
- Full test suite (34+ tests, 7 benchmarks)
- Production-grade linting (11 linters via golangci-lint)
- Vulnerability scanning (govulncheck)
- GitHub Actions CI/CD pipeline

## Key Components

- cmd/audit/: CLI entry point
- internal/inventory/: System inventory parsing
- internal/security/: OSV.dev querying, Claude integration, audit logic
- internal/report/: JSON and HTML report generation
- scripts/collect-inventory.sh: Bash script for system enumeration

## MVP Features

- Homebrew package scanning
- Python/Node/Go/Rust ecosystem scanning
- CVSS-based severity filtering
- Claude-powered recommendations (update/replace/protect/monitor)
- Makefile automation (test, lint, vulnerability checks)
- Pre-commit hooks configuration

## Testing & Quality

- 34+ unit tests with table-driven patterns
- 7 benchmark tests for performance
- 11 configured linters (staticcheck, gosec, revive, etc.)
- Code coverage reporting
- GitHub Actions CI (tests on Go 1.22 & 1.23)
- Pre-commit hook framework

## Documentation

- README.md: Full feature and usage documentation
- QUICKSTART.md: 3-minute setup guide
- TESTING.md: Testing and code quality guide
- QA_SETUP.md: Analysis tooling reference
- DATA_SOURCES_SPEC.md: Vulnerability data source documentation

## Data Sources

- OSV.dev: Primary CVE database (1.8 day latency, no auth needed)
- GitHub Advisories: Supplement for maintainer-created advisories
- OpenSSF Scorecard: Trust signals (repo health/practices)
- Homebrew Formulae API: Package metadata
- CISA KEV: Active exploitation tracking

## Next Steps

Phase 1 (MVP): Complete and tested ✓
Phase 2 (planned): Third-party app scanning, VirusTotal integration
Phase 3 (planned): Historical monitoring, scheduled audits, webhooks

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

QUICKSTART.md

@@ -0,0 +1,146 @@
+# Quick Start Guide
+
+Get a security audit of your Mac in 3 commands.
+
+## Prerequisites
+
+- macOS 11+
+- Go 1.22+ (for development) or compiled binary
+- Claude Code (for Claude integration) or Anthropic API key
+
+## Install Claude Code (optional)
+
+For Claude analysis recommendations:
+
+```bash
+# Option 1: Using Claude Code CLI
+brew install anthropic/claude/claude
+
+# Option 2: Using Anthropic SDK
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Run Audit
+
+### Option A: One Command (if you have make)
+
+```bash
+cd ~/Projects/package-review
+make audit-full
+open audit_report.html
+```
+
+### Option B: Step by Step
+
+```bash
+cd ~/Projects/package-review
+
+# 1. Collect system inventory
+./scripts/collect-inventory.sh
+# Output: inventory.json
+
+# 2. Build the audit tool
+go mod download
+go build -o bin/audit ./cmd/audit
+
+# 3. Run the audit
+./bin/audit
+# Output: audit_report.json, audit_report.html
+
+# 4. Review the report
+open audit_report.html
+```
+
+## Interpreting Results
+
+### Summary Metrics
+- **Total Packages**: All software scanned
+- **With CVEs**: How many packages have known vulnerabilities
+- **HIGH**: CVSS 7.0-8.9 (action recommended)
+- **CRITICAL**: CVSS 9.0+ (urgent action required)
+
+### For Each Finding
+
+**Recommendation** (from Claude):
+- **UPDATE** — Upgrade to a patched version
+- **REPLACE** — Switch to a safer alternative package
+- **PROTECT** — Add extra protections without updating
+- **MONITOR** — Watch for patches; not immediately critical
+
+**Next Steps**: Specific actions to take
+
+## Common Issues
+
+### "Inventory file not found"
+```bash
+./scripts/collect-inventory.sh
+```
+
+### "Claude command not found"
+Use SDK mode instead:
+```bash
+export ANTHROPIC_API_KEY=sk-...
+./bin/audit -claude=sdk
+```
+
+Or skip Claude analysis (findings only):
+```bash
+go run ./cmd/audit 2>/dev/null
+```
+
+### "No findings found"
+This is good! It means:
+- Your packages are up-to-date
+- Or they're not tracked in OSV.dev
+- Check `audit_report.json` for details
+
+## Next Steps
+
+1. **Review high-severity findings** in `audit_report.html`
+2. **Follow Claude's recommendations** for each CVE
+3. **Update packages** in priority order (CRITICAL → HIGH → MEDIUM)
+4. **Re-run audit** after updates:
+   ```bash
+   make audit-full
+   ```
+
+## Output Files
+
+| File | Purpose |
+|------|---------|
+| `inventory.json` | System inventory (JSON) |
+| `audit_report.json` | Findings + recommendations (JSON) |
+| `audit_report.html` | Human-readable report (HTML) |
+
+## Advanced Usage
+
+### Filter by severity
+```bash
+# View only critical findings
+jq '.findings[] | select(.cvss_score >= 9.0)' audit_report.json
+```
+
+### Export for CI/CD
+```bash
+# Fail if critical vulnerabilities found
+if [ $(jq '.summary.critical_findings' audit_report.json) -gt 0 ]; then
+  exit 1
+fi
+```
+
+### Schedule regular audits
+```bash
+# Add to crontab
+0 9 * * 1 cd ~/Projects/package-review && make inventory && ./bin/audit && open audit_report.html
+```
+
+## Documentation
+
+For detailed information, see:
+- **[README.md](./README.md)** — Full documentation
+- **[DATA_SOURCES_SPEC.md](./DATA_SOURCES_SPEC.md)** — Data source details
+- **[Makefile](./Makefile)** — Available commands
+
+---
+
+**Next**: `make audit-full` then `open audit_report.html`