PackageGuard

Secure Python Package Manager with Enhanced Dependency Management

PackageGuard is a Python package manager inspired by Arch Linux's pacman, designed to handle dependency management more effectively than pip. Part of the Guard8.ai ecosystem, PackageGuard provides enhanced security features, comprehensive dependency tracking, and robust package auditing capabilities.

Features

• Advanced Dependency Resolution: Intelligent dependency tree management with conflict detection
• Lock File Management: packageguard.lock ensures reproducible environments across deployments
• Security Auditing: Built-in vulnerability scanning for installed packages
• Comprehensive Logging: Detailed logs for debugging and compliance tracking
• Sync Capabilities: Force environment synchronization with lock file state
• Upgrade Management: Safe package upgrades with version tracking
• Dependency Visualization: Generate and print dependency graphs
• Virtual Environment Integration: Native venv support with isolated package management

Installation

From Source

git clone <repository-url>
cd PackageGuard
pip install -r requirements.txt

Requirements

• Python 3.8+
• networkx==3.3
• packaging==24.1
• requests==2.32.3

Quick Start

1. Create a Virtual Environment

python package_guard.py venv --venv ./my_venv

2. Install Packages

python package_guard.py install requests flask --venv ./my_venv

3. List Installed Packages

python package_guard.py list --venv ./my_venv

4. Sync with Lock File

python package_guard.py sync --venv ./my_venv

Usage

Basic Commands

Install Packages

python package_guard.py install <package_name> --venv <venv_path>
python package_guard.py install requests==2.32.3 --venv ./my_venv

Uninstall Packages

python package_guard.py uninstall <package_name> --venv <venv_path>

Upgrade Packages

python package_guard.py upgrade --venv <venv_path>

List Installed Packages

python package_guard.py list --venv <venv_path>

Generate Dependency Graph

python package_guard.py graph --venv <venv_path>
python package_guard.py print-graph --venv <venv_path>

Audit for Vulnerabilities

python package_guard.py audit --venv <venv_path>

Sync with Lock File

python package_guard.py sync --venv <venv_path>

Module-based Usage

PackageGuard can also be used as a Python module:

from package_guard import PackageGuard

# Initialize PackageGuard
guard = PackageGuard.initialize('./my_venv')

# Install packages
guard.install([('requests', ''), ('flask', '2.3.0')])

# List packages
packages = guard.list()
for pkg in packages:
    print(f"{pkg['name']}=={pkg['version']}")

# Audit for vulnerabilities
vulnerabilities = guard.audit()
if vulnerabilities:
    for vuln in vulnerabilities:
        print(f"Security issue: {vuln['package']} - {vuln['description']}")

# Sync with lock file
guard.sync()

Architecture

PackageGuard follows a modular architecture:

PackageGuard/
├── package_guard/              # Main package directory
│   ├── __init__.py            # Package initialization
│   ├── package_guard.py       # Core PackageGuard class
│   ├── cli.py                 # Command-line interface
│   ├── core/                  # Core functionality
│   │   ├── dependency_tree.py # Dependency tree management
│   │   ├── package_node.py    # Package node representation
│   │   └── version_utils.py   # Version comparison utilities
│   ├── operations/            # Package operations
│   │   ├── install.py         # Installation logic
│   │   ├── uninstall.py       # Uninstallation logic
│   │   ├── upgrade.py         # Upgrade logic
│   │   ├── sync.py            # Synchronization logic
│   │   ├── audit.py           # Security auditing
│   │   └── list_tree.py       # Package listing and tree display
│   └── utils/                 # Utility functions
│       ├── file_operations.py # File I/O operations
│       ├── logging.py         # Logging configuration
│       └── simple_http_client.py # HTTP client for PyPI
├── package_guard.py           # Standalone script
├── package_guard_pure.py      # Pure implementation
├── requirements.txt           # Dependencies
└── README.md                  # This file

Lock File Format

PackageGuard uses packageguard.lock to track installed packages and their dependencies:

{
  "packages": [
    {
      "name": "requests",
      "version": "2.32.3",
      "is_explicit": true,
      "dependencies": ["urllib3", "certifi", "charset-normalizer", "idna"]
    }
  ]
}

Logging

PackageGuard maintains detailed logs in <venv_path>/logs/packageguard.log:

• Console: INFO level by default
• File: DEBUG level with rotation (10MB max, 5 backups)

Adjust logging verbosity:

python package_guard.py install requests --venv ./my_venv --verbose

Security Features

Vulnerability Auditing

PackageGuard checks installed packages against known vulnerabilities:

python package_guard.py audit --venv ./my_venv

The audit command:

• Queries PyPI for package information
• Identifies outdated versions with known security issues
• Provides actionable recommendations

Lock File Integrity

The packageguard.lock file ensures:

• Reproducible builds across environments
• Protection against dependency confusion attacks
• Complete dependency tracking for compliance

Sync Command

The sync command enforces exact environment matching:

• Installs missing packages from lock file
• Removes packages not in lock file
• Verifies versions match lock file specifications

Guard8.ai Integration

PackageGuard is part of the Guard8.ai ecosystem, contributing to the "8th Layer" vision:

• Dependency Security: Vulnerability detection at the package level
• Audit Trails: Complete package installation history for compliance
• Policy Enforcement: Lock file management for enterprise deployments
• Supply Chain Security: Protection against malicious package installations

Differences from pip

Feature	PackageGuard	pip
Dependency Resolution	Advanced graph-based	Basic
Lock File	packageguard.lock	requirements.txt (manual)
Security Auditing	Built-in	Requires separate tools
Sync Capability	Yes	No
Dependency Graph	Visualizable	Limited
Logging	Comprehensive	Minimal

Contributing

PackageGuard is part of the Guard8.ai ecosystem. Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

[Your License Here]

Support

For issues, questions, or contributions:

• GitHub Issues: [Repository URL]
• Documentation: [Docs URL]
• Guard8.ai Ecosystem: See Guard8-Analysis/ecosystem-analysis.md

Roadmap

• Integration with Guard8-SuperAdmin-Console for enterprise management
• Enhanced vulnerability database integration
• Support for private PyPI repositories
• Package signing and verification
• Integration with CI/CD pipelines
• Cloud-based lock file sharing for teams
• Real-time security alerts

Version History

1.0.0 (Current)

• Initial release as PackageGuard (rebranded from Zen)
• Core package management functionality
• Lock file support (packageguard.lock)
• Security auditing capabilities
• Dependency graph visualization
• Comprehensive logging system

---

Part of the Guard8.ai Ecosystem - Responsible AI Development and Deployment