macOS System & Security Analysis Agent CLI (solid-cli)

A local-first macOS security and performance analysis CLI. It runs a unified, adaptive set of analysis agents on your machine and can (optionally) use an LLM (Claude or OpenAI) to generate structured recommendations.

> Note: LLM use is optional. When enabled, the CLI applies prompt sanitization and will abort AI analysis if sensitive patterns are detected.

快速开始（Quick Start）

``bash


Run once (no install)

npx solid-cli

Or install globally

npm install -g solid-cli
solid-cli

Show help

solid-cli --help
`

Optional (enable AI analysis):
`bash
export ANTHROPIC_API_KEY=sk-ant-...


or

export OPENAI_API_KEY=sk-...

solid-cli
`

Reports are written to ./reports/// by default.

Features

- Unified Adaptive Analysis: runs a core set of agents every time, then conditionally expands analysis (e.g. blockchain/DeFi) when indicators are detected.
- Core Security Coverage:
- System integrity checks (SIP, Gatekeeper, updates)
- Persistence mechanism detection (LaunchAgents/LaunchDaemons, Login Items, crontab)
- Process analysis for suspicious activity
- Network connection analysis (optionally enriched with IP geolocation)
- Privacy permission auditing
- Blockchain/DeFi Safety Add-on (adaptive): triggers wallet/DeFi threat checks only when crypto indicators are found.
- Privacy-protected AI insights (optional):
- Provider auto-detection (Claude preferred when both keys exist)
- Prompt sanitization + sensitive-pattern blocking
- Threshold-based skipping when findings are below configured triggers
- Professional Reports: Markdown and/or PDF (Puppeteer) with templates.
- Structured Logging: operational logs under ./logs/.

Architecture

`
┌─────────────┐
│ CLI UI │ inquirer + chalk
└─────┬───────┘
│
┌─────▼────────────────────┐
│ Orchestrator (Unified) │ Phase 1 core + Phase 2 adaptive
└─────┬────────────────────┘
│
┌────▼────┐ ┌───────────────▼───────────────┐
│ Core │ │ Adaptive Agents (conditional) │
│ Agents │ │ Blockchain / DeFi │
└────┬────┘ └───────────────┬───────────────┘
│ │
┌─────▼───────────┐ ┌─────▼───────────┐
│ LLM Analyzer │ │ Report Manager │
│ (optional) │ │ Markdown / PDF │
└──────────────────┘ └─────────────────┘
`

Requirements

- macOS 10.15 or later
- Node.js 20.0 or later
- API Keys (optional): Anthropic Claude and/or OpenAI

Installation

$3

`bash
npm install -g solid-cli
solid-cli
`

Run once without installing:
`bash
npx solid-cli
`

$3

`bash
npm install
npm start
`

Optional: make the entry executable:
`bash
chmod +x src/index.js
`

Usage

Run the interactive CLI:

`bash
solid-cli


or, in this repo


npm start
`

Show help:
`bash
solid-cli --help


or


npm start -- --help
`

$3

1. LLM auto-detection (no manual provider picker)
- If ANTHROPIC_API_KEY is present, the CLI uses Claude.
- Else if OPENAI_API_KEY is present, it uses OpenAI.
- Else it runs report-only.
2. AI analysis option: you can still choose AI analysis or report-only.
3. Report format: PDF or Markdown.
4. IP geolocation: controlled by config (security.enableGeoLookup) and shown in the run summary.
5. Analysis starts automatically (no extra confirmation prompt).

$3

- Default output root: ./reports (configurable via reports.outputDir).
- Directory layout: ./reports///
- Filenames:
- Security-Report-.md
- Security-Report-.pdf
- metadata-.json

$3

`text
$ solid-cli

✅ Claude (Anthropic) - API key detected
? 🤖 AI Analysis Option: (Use arrow keys)
🧠 Use AI Analysis (CLAUDE) - Enhanced insights & recommendations
📋 Generate Security Report Only - Maximum privacy protection

? Select report format: PDF (.pdf)
✅ IP geolocation enabled

🔍 Starting unified adaptive analysis...

Phase 1: Core Security Analysis
✓ ResourceAgent completed - Risk: LOW
✓ SystemAgent completed - Risk: MEDIUM
...

Phase 2: Adaptive Analysis
No blockchain indicators detected - skipping blockchain analysis

📁 Saved Reports:
📑 Pdf: reports/2025/December/Security-Report-RPT-XXXXXX.pdf
`

Agents

$3

- ResourceAgent: CPU/memory/process resource usage heuristics.
- SystemAgent: SIP/Gatekeeper/updates and other system posture checks.
- PersistenceAgent: LaunchAgents/LaunchDaemons/Login Items/crontab.
- ProcessAgent: suspicious process patterns (paths, elevation, obfuscation).
- NetworkAgent: network connections and listening ports; optional IP geolocation enrichment.
- PermissionAgent: privacy permission auditing.

$3

- BlockchainAgent: wallet processes/files, wallet-like browser extensions, mining indicators, and blockchain/DeFi network patterns.
- DeFiSecurityAgent: DeFi scam indicators (processes/download metadata/network) with privacy-protective behavior (no clipboard or browser-history content extraction).

Configuration

This project uses the config (node-config) package.

- Defaults ship in config/default.json.
- You can override settings by providing your own config directory in one of these ways:
- Create ./config/local.json in the directory where you run solid-cli.
- Or set NODE_CONFIG_DIR to a custom config folder.

Common settings:

- reports.outputDir: report output directory (default ./reports).
- analysis.parallelExecution and analysis.maxParallelAgents: speed vs. load tradeoff.
- security.enableGeoLookup and security.geoLookupLimit: IP geolocation enrichment behavior.
- llm.mode: prompt mode (summary / full).
- llm.minHighRiskFindings, llm.minTotalFindings, llm.skipWhenBelowThreshold: when AI analysis should run.

AI / LLM behavior (privacy-protected)

- Provider auto-detection priority: Claude → OpenAI → none.
- Before any LLM call, the CLI:
- builds a prompt from analysis results,
- runs a sensitive pattern scan,
- and skips AI analysis (and records details into report metadata) if sensitive patterns are detected.
- When AI analysis runs, request/response payloads are logged under ./logs/llm-requests/.

Security Considerations

- No Root Required: checks run with user permissions.
- Local-First: analysis runs locally; AI is optional.
- Read-only: the tool does not modify system settings.
- LLM Safety: sensitive pattern detection can prevent accidental leakage of keys/tokens.

Troubleshooting

$3

Some checks may be limited without:
- Full Disk Access (e.g. some system databases)
- Accessibility (some process visibility)

$3

PDF uses Puppeteer. If Chromium cannot launch:
- reinstall dependencies so Puppeteer can fetch Chromium, or
- set PUPPETEER_EXECUTABLE_PATH to a local Chrome/Chromium.

Development

$3

`text
solid-cli/
├── config/
│ └── default.json # node-config defaults
├── src/
│ ├── agents/ # analysis agents
│ ├── config/ConfigManager.js # config access/validation
│ ├── llm/LLMAnalyzer.js # LLM prompt building + safety checks
│ ├── logging/Logger.js # structured logging
│ ├── report/ # report generation (Handlebars + Puppeteer)
│ ├── utils/ # shell helpers, signatures, etc.
│ ├── Orchestrator.js # unified adaptive runner
│ └── index.js # CLI entry point
├── reports/ # generated reports (gitignored typically)
├── logs/ # generated logs (gitignored typically)
└── README.md
`

$3

1. Create a new agent extending BaseAgent and implement analyze().
2. Register it in src/Orchestrator.js (core or conditional).

Publishing to npm (maintainers)

1. Update package.json metadata (name/scope, version, repository, bugs, homepage).
2. Clean artifacts: remove generated logs/ and reports/ before packing.
3. Verify package contents: npm pack --dry-run.
4. Smoke tests (non-interactive helpers):
- node src/index.js --help
- node test-llm-choice.js
- node test-llm-blocking.js
- node test-llm-privacy.js
- node test-blockchain.js
5. Publish: npm publish --access public.

License

MIT License - see LICENSE`.

Disclaimer

This tool is for legitimate security analysis and system auditing only. Users are responsible for compliance with applicable laws and regulations. The authors assume no liability for misuse.