MWA3 - MunkiWebAdmin 3

Introduction

MunkiWebAdmin 3 (MWA3) is a modern, Django-based web administration tool for Munki. It provides a comprehensive interface for managing Munki repositories, including package information, manifests, catalogs, and icons.

Features

• Package Management: Upload, edit, and manage package information (pkgsinfo)
• Manifest Management: Create and manage client manifests
• Catalog Management: View and manage Munki catalogs
• Icon Management: Upload and manage application icons
• Vulnerability Scanning: Integrated CVE/NIST vulnerability scanning for packages
• REST API: Full REST API for programmatic access
• Authentication: Support for Azure AD/ADFS and LDAP authentication
• Multi-Storage: Support for local filesystem, Azure Blob Storage
• Docker Support: Production-ready Docker containers

Quick Start

Docker (Recommended)

1. Clone the repository:

git clone https://github.com/SteveKueng/munkiwebadmin.git
cd munkiwebadmin

2. Create a .env file with your configuration:

SECRET_KEY=your-secure-secret-key-here
DB=postgres
DB_NAME=munkiwebadmin
DB_USER=munkiwebadmin_user
DB_PASS=your-secure-password
DB_HOST=db
DB_PORT=5432
ALLOWED_HOSTS=localhost 127.0.0.1

3. Start with Docker Compose:

cd docker
docker-compose -f docker-compose.prod.yml up -d

4. Access at http://localhost:80

Manual Installation

Requirements

• Python 3.11+
• PostgreSQL, MySQL, or SQLite
• libmagic (for file type validation)

Installation Steps

1. Install system dependencies (Ubuntu/Debian):

apt-get install python3.11 python3-pip libmagic1 postgresql-client

2. Clone and install Python dependencies:

git clone https://github.com/SteveKueng/munkiwebadmin.git
cd munkiwebadmin
pip install -r requirements.txt

3. Configure environment variables (see Configuration section)

4. Run migrations:

python manage.py migrate

5. Create superuser:

python manage.py createsuperuser

6. Collect static files:

python manage.py collectstatic

7. Start the development server:

python manage.py runserver

Configuration

Required Environment Variables

Variable	Description	Default
SECRET_KEY	Django secret key (MUST be set in production)	N/A
ALLOWED_HOSTS	Space-separated list of allowed hosts	localhost 127.0.0.1
MUNKI_REPO_URL	Munki repository URL	file:///munkirepo

Database Configuration

Choose your database backend:

PostgreSQL (Recommended):

DB=postgres
DB_NAME=munkiwebadmin
DB_USER=munkiwebadmin_user
DB_PASS=your-password
DB_HOST=localhost
DB_PORT=5432

MySQL:

DB=mysql
DB_NAME=munkiwebadmin
DB_USER=munkiwebadmin_user
DB_PASS=your-password
DB_HOST=localhost
DB_PORT=3306

SQLite (Development only):

# No additional configuration needed

Security Settings

# HTTPS/SSL
SECURE_SSL_REDIRECT=True
CSRF_COOKIE_SECURE=True
SECURE_HSTS_SECONDS=31536000

# CSRF Protection
CSRF_TRUSTED_ORIGINS=https://yourdomain.com

# Rate Limiting
THROTTLE_ANON=100/hour
THROTTLE_USER=1000/hour
THROTTLE_UPLOADS=10/hour

Authentication

Azure AD/ADFS:

CLIENT_ID=your-azure-client-id
CLIENT_SECRET=your-azure-client-secret
TENANT_ID=your-azure-tenant-id
ENTRA_ONLY=True

LDAP: Set USE_LDAP=True in settings.py and configure LDAP settings.

Optional Settings

# Application
APPNAME=MunkiWebAdmin
DEBUG=False
LANGUAGE_CODE=en-us
TIME_ZONE=UTC

# Package Display
ENABLE_REPO_VIEW=True
CATALOGS_TO_DISPLAY=production testing development
SHOW_ICONS=True

# Vulnerability Scanning
NIST_API_KEY=your-nist-api-key

REST API

MWA3 provides a full REST API for programmatic access:

• Authentication: Basic Auth, Session Auth, or Azure AD Token
• Endpoints:
  • /api/catalogs/ - Catalog management
  • /api/manifests/ - Manifest management
  • /api/pkgsinfo/ - Package info management
  • /api/pkgs/ - Package uploads
  • /api/icons/ - Icon management

API Example

# List all catalogs
curl -u username:password https://yourserver/api/catalogs/

# Upload a package
curl -X POST -F "file=@package.pkg" \
  -u username:password \
  https://yourserver/api/pkgs/packages/apps/

Security Best Practices

Production Deployment Checklist

• Set unique SECRET_KEY (never use default!)
• Set DEBUG=False
• Configure proper ALLOWED_HOSTS
• Use HTTPS/SSL (SECURE_SSL_REDIRECT=True)
• Enable CSRF protection (CSRF_COOKIE_SECURE=True)
• Configure rate limiting
• Use strong database passwords
• Run container as non-root user (already configured)
• Keep dependencies updated (enable Dependabot)
• Regular security audits

Known Security Considerations

• File uploads are validated using magic bytes (not just extensions)
• Access tokens are never logged
• CSRF protection is enabled for all state-changing operations
• Rate limiting prevents abuse
• Security headers (HSTS, X-Frame-Options) are configured

Development

Running Tests

python manage.py test

Code Style

# Install development dependencies
pip install flake8 black

# Format code
black .

# Lint
flake8 .

Project Structure

mwa3/
├── api/              # REST API endpoints
├── catalogs/         # Catalog management
├── manifests/        # Manifest management
├── pkgsinfo/         # Package info management
├── icons/            # Icon management
├── vulnerabilities/  # CVE scanning
├── munkiwebadmin/    # Main Django project
└── docker/           # Docker configuration

Troubleshooting

Common Issues

1. Database Connection Failed

• Check database credentials in environment variables
• Ensure database service is running
• Verify network connectivity

2. Static Files Not Loading

• Run python manage.py collectstatic
• Check STATIC_ROOT and STATIC_URL settings

3. Unauthorized API Access

• Verify authentication credentials
• Check API permissions in Django admin

4. File Upload Fails

• Check MUNKI_REPO_URL configuration
• Verify write permissions on repository directory
• Ensure file is valid PKG or DMG format

Contributing

Contributions are welcome! Please:

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

Support

• Documentation: Check the wiki
• Issues: Report bugs on GitHub Issues
• Discussions: Join discussions in the Munki community

License

See LICENSE file for details.

Credits

MunkiWebAdmin is built on:

• Django
• Django REST Framework
• Munki

---

Note: This is version 3 of MunkiWebAdmin, a complete rewrite with modern architecture and security best practices.