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