SysMap 🗺️

---

Features

Multi-Platform Package Manager Support

• Windows: WinGet, Chocolatey, Scoop
• macOS: Homebrew
• Linux: Snap, Flatpak, APT/dpkg
• Cross-Platform: pip (Python), npm (Node.js)

Multiple Export Formats

• Markdown - Beautiful human-readable reports
• JSON - Machine-readable for automation
• YAML - Configuration-friendly format
• CSV - Import into spreadsheets
• HTML - Interactive web-based reports with search

Advanced Features

• Version Comparison - Compare system snapshots and track changes
• Update Detection - Find outdated packages across all package managers
• Watch Mode - Continuously monitor for system changes
• Configuration Files - Customize scanning behavior
• Plugin System - Extend with custom scanners
• Rich CLI - Beautiful terminal output with colors and tables

Use Cases

• DevOps: Document development environment setups
• System Administration: Audit software installations
• Team Onboarding: Share standardized environment configurations
• Compliance: Track software versions for security audits
• CI/CD: Auto-generate environment documentation

---

Installation

Via pip (Recommended)

pip install sysmap

From Source

git clone https://github.com/lorenzouriel/sysmap.git
cd sysmap
pip install -e .

With Development Dependencies

pip install -e ".[dev]"

---

Quick Start

Basic Scan

Generate a system inventory report:

sysmap scan

Output: SYSTEM_SUMMARY.md

Check for Updates

Find outdated packages:

sysmap scan --check-updates

Export to Different Formats

# JSON format
sysmap scan --format json --output system.json

# HTML interactive report
sysmap scan --format html --output report.html

# CSV for spreadsheets
sysmap scan --format csv --output packages.csv

Compare Snapshots

# Create baseline
sysmap scan --format json --output baseline.json

# ... time passes, install/update packages ...

# Compare current system to baseline
sysmap diff baseline.json

# Or compare two snapshots
sysmap diff baseline.json current.json

Watch for Changes

Monitor your system in real-time:

sysmap watch --interval 60

Quick Summary

sysmap summary

---

Usage Examples

Configuration File

Create a custom configuration:

sysmap init

This creates .sysmap.yaml:

scanners:
  winget: true
  pip: true
  npm: true
  brew: true
  chocolatey: true
  scoop: true
  snap: true
  flatpak: true

output:
  format: markdown
  path: SYSTEM_SUMMARY.md

features:
  check_updates: false
  security_scan: false

plugins: []

Use Custom Config

sysmap scan --config my-config.yaml

Check Only Specific Package Managers

Edit .sysmap.yaml to disable unwanted scanners:

scanners:
  winget: true
  pip: true
  npm: false  # Disable npm scanning
  brew: false  # Disable Homebrew

---

Example Output

Terminal Output

╭─────────── Package Summary ───────────╮
│ Package Manager │ Packages │ Updates │
│─────────────────│──────────│─────────│
│ Winget          │      104 │       8 │
│ Pip             │       25 │       3 │
│ Npm             │       42 │       5 │
│ Total           │      171 │      16 │
╰───────────────────────────────────────╯

Markdown Report

See SYSTEM_SUMMARY.md for a full example.

HTML Report

Interactive, searchable web page with:

• Platform information
• Package summaries
• Live search/filter
• Color-coded updates
• Responsive design

---

CLI Reference

Commands

Command	Description
sysmap scan	Scan system and generate inventory
sysmap diff	Compare two system snapshots
sysmap watch	Monitor system for changes
sysmap summary	Display quick package summary
sysmap updates	Check for available updates
sysmap init	Create default config file

Global Options

Option	Description
--version	Show version
--help	Show help message

Scan Options

Option	Description
-f, --format	Output format (markdown/json/yaml/csv/html)
-o, --output	Output file path
--check-updates	Check for package updates
-c, --config	Path to config file

---

Architecture

sysmap/
├── core/
│   ├── scanner.py      # Package manager scanners
│   └── config.py       # Configuration management
├── exporters/
│   ├── markdown.py     # Markdown exporter
│   ├── json_exporter.py
│   ├── yaml_exporter.py
│   ├── csv_exporter.py
│   └── html_exporter.py
├── utils/
│   ├── diff.py         # Snapshot comparison
│   └── watch.py        # Watch mode
└── cli.py              # Command-line interface

---

Contributing

We love contributions! Please see CONTRIBUTING.md for details on:

• Reporting bugs
• Suggesting features
• Submitting pull requests
• Development setup
• Coding standards

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pytest)
5. Format code (black src/ and ruff check src/)
6. Commit (git commit -m 'feat: add amazing feature')
7. Push (git push origin feature/amazing-feature)
8. Open a Pull Request

🛠️ Development

Setup

git clone https://github.com/lorenzouriel/sysmap.git
cd sysmap
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

Run Tests

pytest
pytest --cov=sysmap  # With coverage

Code Quality

black src/           # Format code
ruff check src/      # Lint code
mypy src/            # Type checking

---

📊 Project Stats

• Lines of Code: ~2,000+
• Test Coverage: 85%+
• Supported Package Managers: 8
• Export Formats: 5
• Python Versions: 3.8+

---

🎯 Real-World Use Cases

DevOps Teams

# Document your development environment
sysmap scan --format json --output team-environment.json

# Share with the team via Git
git add team-environment.json
git commit -m "docs: update team environment specs"
git push

System Administrators

# Weekly audit of all servers
sysmap scan --check-updates --format html --output audit-$(date +%Y%m%d).html

# Compare with last week's baseline
sysmap diff audit-baseline.json

CI/CD Pipelines

# .github/workflows/env-check.yml
- name: Document Environment
  run: |
    sysmap scan --format json --output build-env.json

- name: Upload Artifact
  uses: actions/upload-artifact@v4
  with:
    name: build-environment
    path: build-env.json

Compliance & Security

# Generate compliance report
sysmap scan --format csv --output compliance-report.csv

# Check for outdated packages (security risk)
sysmap updates --format json > security-audit.json

---

❓ FAQ

Q: Does SysMap require admin/root privileges?

A: No, SysMap runs with user permissions. Some package managers may require privileges for update checks.

Q: Can I use SysMap on Windows/macOS/Linux?

A: Yes! SysMap is cross-platform and automatically detects available package managers.

Q: How do I add support for a new package manager?

A: See CONTRIBUTING.md for instructions on adding new scanners.

Q: Is my data sent anywhere?

A: No, all scanning happens locally. SysMap doesn't phone home or collect telemetry.

Q: Can I use this in commercial projects?

A: Yes! SysMap is MIT licensed - use it freely in commercial and personal projects.

Q: How often should I run scans?

A: For personal use: weekly. For production servers: daily or use watch mode.

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---