qvfd8gl0/macos-package-review
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
macos-package-review/QUICKSTART.md
T
ClaudeandClaude Haiku 4.5 f8adf0669c
CI / Test (1.22) (push) Has been cancelled
Details
CI / Test (1.23) (push) Has been cancelled
Details
CI / Lint (push) Has been cancelled
Details
CI / Vulnerability Check (push) Has been cancelled
Details
CI / Format Check (push) Has been cancelled
Details
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>
2026-06-23 04:56:57 -07:00

3.1 KiB
Raw Permalink Blame History

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:

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

cd ~/Projects/package-review
make audit-full
open audit_report.html

Option B: Step by Step

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"

./scripts/collect-inventory.sh

"Claude command not found"

Use SDK mode instead:

export ANTHROPIC_API_KEY=sk-...
./bin/audit -claude=sdk

Or skip Claude analysis (findings only):

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: 
    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

# View only critical findings
jq '.findings[] | select(.cvss_score >= 9.0)' audit_report.json

Export for CI/CD

# Fail if critical vulnerabilities found
if [ $(jq '.summary.critical_findings' audit_report.json) -gt 0 ]; then
  exit 1
fi

Schedule regular audits

# Add to crontab
0 9 * * 1 cd ~/Projects/package-review && make inventory && ./bin/audit && open audit_report.html

Documentation

For detailed information, see:

Next: make audit-full then open audit_report.html

Reference in New Issue View Git Blame Copy Permalink