ClaudeandClaude Haiku 4.5
f8adf0669c
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>
147 lines
3.1 KiB
Markdown
147 lines
3.1 KiB
Markdown
# 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`
|