{"id":46558966,"url":"https://github.com/windowsadmins/cimian","last_synced_at":"2026-07-19T02:04:38.538Z","repository":{"id":300471125,"uuid":"949235407","full_name":"windowsadmins/cimian","owner":"windowsadmins","description":"Cimian is a managed software deployment system for .msi, .msix, .exe, .nupkg, and pwsh scripts for Windows written in C#","archived":false,"fork":false,"pushed_at":"2026-06-17T02:45:59.000Z","size":13756,"stargazers_count":15,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-17T04:25:48.275Z","etag":null,"topics":["devops","gitops","software-deployment","windows-administration"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/windowsadmins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-16T01:20:17.000Z","updated_at":"2026-06-13T07:07:21.000Z","dependencies_parsed_at":"2025-07-23T22:26:44.009Z","dependency_job_id":"dd66475e-eabc-44c1-a01b-4e6a7ab9b6c7","html_url":"https://github.com/windowsadmins/cimian","commit_stats":null,"previous_names":["windowsadmins/cimian"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/windowsadmins/cimian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windowsadmins%2Fcimian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windowsadmins%2Fcimian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windowsadmins%2Fcimian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windowsadmins%2Fcimian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/windowsadmins","download_url":"https://codeload.github.com/windowsadmins/cimian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/windowsadmins%2Fcimian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35637765,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-19T02:00:06.923Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devops","gitops","software-deployment","windows-administration"],"created_at":"2026-03-07T05:21:59.416Z","updated_at":"2026-07-19T02:04:38.525Z","avatar_url":"https://github.com/windowsadmins.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cimian\n\nCimian is an open-source software deployment solution designed for managing and automating software installations on Windows. **Heavily** inspired by the wonderful and dearly loved [Munki](https://github.com/munki/munki) project, Cimian allows Windows admins to manage software packages through a webserver-based repository of packages and metadata, enabling automated deployments, updates, and removals **at scale** in a programmatic manner. Cimian is built with modern Windows environments in mind, supporting both x64 and ARM64 architectures, and is optimized for integration with Microsoft Intune and device management services.\n\nCimian aims to allow Mac Admins that manage Windows with Munki to have the exact same experience on Windows and to provide Windows Admins with a powerful and flexible tool for software management or those looking to transition away from traditional imaging and towards modern management with Git and DevOps principles.\n\nCimian is developed in C# using .NET 10. It leverages a YAML-based configuration system for easy management and customization, and includes native a WPF GUI application for end-user self-service software installation.\n\nCimian is ideal for organizations of all sizes looking to streamline their Windows software deployment processes. It can be used in small environments with just a few machines, or scaled up to manage thousands of systems across multiple locations.\n\n![msc](https://github.com/windowsadmins/cimian/blob/main/msc-light.png?raw=true)\n\n## Key Features\n\n- **Automated Package Management**: Streamline software packaging, metadata management, and distribution\n- **Flexible YAML Configuration**: Easily configure and manage settings through clear, YAML-based config files\n- **Multi-format Installer Support**: Supports MSI, MSIX, EXE, PowerShell scripts, and NuGet .nupkg custom packages formats\n- **Bootstrap Mode**: for zero-touch deployment and system provisioning\n- **Conditional Items**: Advanced evaluation system for dynamic software deployment based on system facts (hostname, architecture, OS version, domain, machine type, etc.) with simplified string syntax\n- **Enterprise Integration**: Built for Microsoft Intune with .intunewin support and other Deployment Management Services.\n\n## Architecture Overview\n\nCimian consists of a suite of command-line tools, system services, and apps:\n\n### Core Binaries\n\nAll binaries are built for both x64 and arm64 architectures and installed to `C:\\Program Files\\Cimian\\`.\n\n#### Client-Side Management\n\n**`managedsoftwareupdate.exe`** - *Primary Client Agent*\n- Core client-side component for software installation and management\n- Handles automatic software updates, installations, and removals\n- Supports bootstrap mode for zero-touch deployments\n- Manages software manifests and catalog synchronization\n- Features comprehensive logging and error handling\n- Supports multiple installer types (MSI, EXE, PowerShell, file copying)\n- Includes self-update capabilities and privilege elevation\n- Provides command-line interface for administrative tasks\n\n**`manifestutil.exe`** - *Manifest Management Tool*\n- Command-line utility for managing deployment manifests\n- Creates, modifies, and maintains software deployment lists\n- Supports adding/removing packages from managed installations\n- Handles self-service software request management\n- Provides manifest validation and organization\n\n#### Package Management Tools\n\n**`cimiimport.exe`** - *Package Import and Metadata Generator*\n- Automates importing software installers and generating deployment metadata\n- Supports MSI, EXE, PowerShell scripts, and file-based installations\n- Extracts metadata automatically (version, product codes, dependencies)\n- Generates YAML pkginfo files with installation instructions\n- Integrates with cloud storage (AWS S3, Azure Blob Storage) for package distribution\n- Handles script integration (pre/post install and uninstall scripts)\n- Features interactive and non-interactive configuration modes\n\n**`cimipkg.exe`** - *NuGet Package Creator*\n- Creates deployable NuGet packages (.nupkg) from project directories\n- Supports both installer-type and copy-type package deployments\n- Generates Chocolatey-compatible installation scripts\n- Handles PowerShell script signing and embedding\n- Optionally creates .intunewin packages for Microsoft Intune deployment\n- Manages version normalization and metadata validation\n\n**`makecatalogs.exe`** - *Software Catalog Generator*\n- Scans repository and generates software catalogs from pkginfo metadata\n- Creates organized YAML catalog files (Testing, Production, All, etc.)\n- Validates package payload integrity and reports missing files\n- Supports catalog-based software targeting and deployment\n\n**`makepkginfo.exe`** - *Package Info Generator*\n- Creates pkginfo metadata files for software packages\n- Extracts installer metadata and generates deployment configurations\n- Supports direct package analysis and metadata generation workflows\n\n**`repoclean.exe`** - *Repository Cleaner*\n- Removes older, unused software items from a Cimian repository\n- Keeps a configurable number of recent versions per package (`--keep`, default 2)\n- Runs as a dry-run by default; use `--remove` to actually delete\n- Supports `--auto` for non-interactive cleanup in CI/CD pipelines\n\n#### Deployment Triggers and Monitoring\n\n**`cimitrigger.exe`** - *Deployment Trigger Tool*\n- Initiates software deployment processes on-demand\n- Supports both GUI and headless deployment modes\n- Handles privilege elevation and process management\n- Provides diagnostic capabilities for troubleshooting\n- Integrates with CimianWatcher service for responsive deployments\n\n**`cimiwatcher.exe`** - *Bootstrap Monitoring Service*\n- Windows service that monitors for deployment trigger files\n- Enables near-real-time software deployment via MDM platforms\n- Supports dual-mode operation (GUI and headless bootstrap)\n- Handles automatic service recovery and error management\n- Integrates with self-update system for service maintenance\n- Provides comprehensive event logging for enterprise monitoring\n\n#### User Interface\n\n**`Managed Software Center.exe`** - *End-User Self-Service Application*\n- WinUI 3 application providing a self-service software catalog\n- Browse, install, update, and remove optional software without admin rights\n- Organized pages for Software, Categories, My Items, Updates, and History\n- Item detail views with descriptions, screenshots, and version info\n- Built-in log viewer for diagnosing installation issues\n- Theme-aware UI that follows the Windows system light/dark setting\n\n## Repository Structure\n\nA typical Cimian repository follows this structure:\n\n```\nCimianRepo/\n├── catalogs/           # Generated catalog files\n│   ├── All.yaml\n│   ├── Testing.yaml\n│   └── Production.yaml\n├── manifests/          # Client deployment manifests\n│   ├── site_default.yaml\n│   └── computer_groups/\n├── pkgs/              # Software package storage\n│   ├── Adobe/\n│   ├── Microsoft/\n│   └── ...\n└── pkgsinfo/          # Package metadata\n    ├── Adobe/\n    └── Microsoft/\n```\n\n## Command Line Examples\n\n`managedsoftwareupdate`:\n\n```pwsh\nsudo managedsoftwareupdate --help   \nUsage of C:\\Program Files\\Cimian\\managedsoftwareupdate.exe:\n      --auto                         Perform automatic updates.\n      --cache-status                 Show cache status and statistics.\n      --check-selfupdate             Check if self-update is pending.\n      --checkonly                    Check for updates, but don't install them.\n      --clear-bootstrap-mode         Disable bootstrap mode.\n      --clear-selfupdate             Clear pending self-update flag.\n      --installonly                  Install pending updates without checking for new ones.\n      --item strings                 Install only the specified package name(s). Can be repeated or given as a comma-separated list.\n      --local-only-manifest string   Use specified local manifest file instead of server manifest.\n      --manifest string              Process only the specified manifest from server (e.g., 'Shared/Curriculum/RenderingFarm'). Automatically skips preflight.\n      --no-postflight                Skip postflight script execution.\n      --no-preflight                 Skip preflight script execution.\n      --perform-selfupdate           Perform pending self-update (internal use).\n      --postflight-only              Run only the postflight script and exit.\n      --preflight-only               Run only the preflight script and exit.\n      --restart-service              Restart CimianWatcher service and exit.\n      --selfupdate-status            Show self-update status and exit.\n      --set-bootstrap-mode           Enable bootstrap mode for next boot.\n      --show-config                  Display the current configuration and exit.\n      --show-status                  Show status window during operations (bootstrap mode).\n      --validate-cache               Validate cache integrity and remove corrupt files.\n  -v, --verbose count                Increase verbosity (e.g. -v, -vv, -vvv, -vvvv)\n      --version                      Print the version and exit.\npflag: help requested\n```\n\n```pwsh\n# Import a new software package\ncimiimport.exe \"C:\\Installers\\Firefox.exe\" --arch x64\n\n# Create a NuGet package from project directory\ncimipkg.exe \"C:\\Projects\\MyApp\"\n\n# Generate catalogs from repository\nmakecatalogs.exe\n\n# Add software to managed installations\nmanifestutil.exe --add-pkg \"Firefox\" --manifest \"site_default\"\n\n# Check for and install updates\nmanagedsoftwareupdate.exe --auto\n\n# Run only preflight script for testing\nmanagedsoftwareupdate.exe --preflight-only\n\n# Run only postflight script for testing\nmanagedsoftwareupdate.exe --postflight-only\n\n# Trigger GUI update process\ncimitrigger.exe gui\n\n# Run diagnostic tests\ncimitrigger.exe debug\n```\n\n## Installation and Deployment\n\n### Distribution Formats\n\nCimian is distributed in multiple formats to support different deployment scenarios:\n\n- **MSI Packages**: `Cimian-x64-{version}.msi` and `Cimian-arm64-{version}.msi` for traditional Windows deployment\n- **NuGet Packages**: `CimianTools-x64-{version}.nupkg` and `CimianTools-arm64-{version}.nupkg` for Chocolatey-based deployment  \n- **Intune Packages**: `.intunewin` files for Microsoft Intune deployment\n\n### Quick Start\n\n1. **Download and Install**: Deploy the appropriate MSI package for your architecture\n2. **Configure Repository**: Edit `C:\\ProgramData\\ManagedInstalls\\Config.yaml` with your repository settings\n3. **Import Software**: Use `cimiimport.exe` to import software packages into your repository\n4. **Generate Catalogs**: Run `makecatalogs.exe` to create software catalogs\n5. **Deploy**: Use bootstrap mode or direct execution for software deployment\n\n## Bootstrap System\n\nCimian includes a bootstrap system similar to Munki's, designed for zero-touch deployment scenarios where machines must complete all required software installations before users can log in.\n\n### How Bootstrap Works\n\n1. **Trigger Files**: \n   - `C:\\ProgramData\\ManagedInstalls\\.cimian.bootstrap` - Bootstrap with GUI status window\n   - `C:\\ProgramData\\ManagedInstalls\\.cimian.headless` - Bootstrap without GUI (silent)\n\n2. **CimianWatcher Service**: A Windows service monitors bootstrap trigger files every 10 seconds and automatically initiates software deployment\n\n3. **Dual Mode Operation**: \n   - **GUI Mode**: Shows CimianStatus window for visual progress monitoring\n   - **Headless Mode**: Silent operation for automated scenarios\n\n4. **Automatic Process Management**: The service handles process elevation, error recovery, and cleanup automatically\n\n5. **Integration Points**: Works seamlessly with MDM platforms like Microsoft Intune for enterprise deployment\n\n### Bootstrap Commands\n\n| Action | Command | Description |\n|--------|---------|-------------|\n| Enter GUI Bootstrap | `managedsoftwareupdate.exe --set-bootstrap-mode` | Creates GUI bootstrap trigger |\n| Enter Headless Bootstrap | `cimitrigger.exe headless` | Initiates silent bootstrap |\n| Clear Bootstrap | `managedsoftwareupdate.exe --clear-bootstrap-mode` | Removes bootstrap flags |\n| Trigger GUI Update | `cimitrigger.exe gui` | Force GUI update process |\n| Diagnostic Mode | `cimitrigger.exe debug` | Run diagnostics |\n\n### Enterprise Use Cases\n\n- **Zero-touch deployment**: Ship Windows machines with only Cimian installed; bootstrap completes the configuration\n- **System rebuilds**: Ensure all required software is installed before first user login  \n- **Provisioning automation**: Integrate with deployment tools for fully automated system setup\n- **MDM Integration**: Deploy via Microsoft Intune with .intunewin packages\n- **Responsive Updates**: Near-real-time software deployment when triggered by management systems\n\n### PowerShell Integration\n\n```pwsh\n# Example: Automated package import workflow\n$packages = Get-ChildItem \"C:\\Installers\" -Filter \"*.exe\"\nforeach ($package in $packages) {\n    \u0026 \"C:\\Program Files\\Cimian\\cimiimport.exe\" $package.FullName --arch x64\n}\n\n# Generate catalogs after import\n\u0026 \"C:\\Program Files\\Cimian\\makecatalogs.exe\"\n```\n\n## Development and Building\n\n### Build System\n\nThe project uses a comprehensive PowerShell build system (`build.ps1`) that:\n\n- Builds all binaries for x64 and ARM64 architectures\n- Handles code signing with enterprise certificates\n- Creates MSI and NuGet packages automatically\n- Supports development mode for rapid iteration\n- Integrates with CI/CD pipelines\n\n### Build Commands\n\n```pwsh\n# Full build with automatic signing\n.\\build.ps1 -Sign\n\n# Build specific binary only\n.\\build.ps1 -Binary cimistatus -Sign\n\n# Build all binaries without packaging\n.\\build.ps1 -Sign -Binaries\n\n# Create Intune packages\n.\\build.ps1 -Sign -IntuneWin\n\n# Package existing binaries without rebuilding\n.\\build.ps1 -Sign -PackageOnly\n```\n\n### Environment Configuration\n\nThe build system uses environment variables for sensitive configuration data such as code signing certificates.\n\n#### Setup\n\n1. Copy `.env.example` to `.env`:\n   ```powershell\n   Copy-Item .env.example .env\n   ```\n\n2. Edit `.env` with your organization's certificate information:\n   ```\n   CIMIAN_CERT_CN=YourOrganization Enterprise Certificate\n   CIMIAN_CERT_SUBJECT=YourOrganization\n   ```\n\n#### Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `CIMIAN_CERT_CN` | Full certificate common name | `\"Contoso Enterprise Certificate\"` |\n| `CIMIAN_CERT_SUBJECT` | Certificate subject pattern for auto-detection | `\"Contoso\"` |\n| `CIMIAN_CERT_THUMBPRINT` | (Optional) Override certificate thumbprint | `\"1234567890ABCDEF...\"` |\n| `CIMIAN_CERT_STORE` | (Optional) Certificate store location | `\"CurrentUser\"` or `\"LocalMachine\"` |\n\n\u003e **Security Note**: The `.env` file is automatically ignored by git and should never be committed. Always use `.env.example` as a template for new environments.\n\n### Worktrees\n\nNew worktrees should be created with `.\\scripts\\new-worktree.ps1` so the nested `cli/cimipkg` submodule is initialised automatically. Plain `git worktree add` skips submodules and the build will fail until they are initialised manually.\n\n```pwsh\n# Create a feature worktree with the cli/cimipkg submodule ready to build\n.\\scripts\\new-worktree.ps1 .claude/worktrees/my-feature -b feature/my-feature\n```\n\n## Configuration\n\nCimian uses a YAML-based configuration system located at `C:\\ProgramData\\ManagedInstalls\\Config.yaml`:\n\n```yaml\n# Basic Configuration\nsoftware_repo_url: https://cimian.yourdomain.com/\nclient_identifier: MyComputer-01\nforce_basic_auth: false\ndefault_arch: x64\ndefault_catalog: Testing\n\n# Repository Settings  \nrepo_path: \"C:\\\\CimianRepo\"\ncloud_provider: none  # Options: aws, azure, none\nmanaged_installs_dir: \"C:\\\\ProgramData\\\\ManagedInstalls\"\n\n# Update Behavior\nauto_update_enabled: true\nauto_update_check_interval: 24  # hours\ninstaller_timeout_minutes: 30\nmax_concurrent_downloads: 3\n\n# Logging Configuration\nlog_level: INFO  # Options: DEBUG, INFO, WARNING, ERROR\nlog_max_size_mb: 10\nlog_retention_days: 30\n\n# Bootstrap Settings\nbootstrap_timeout_minutes: 120\nbootstrap_retry_attempts: 3\n\n# Advanced Options\nuse_tls_verification: true\nproxy_server: \"\"\ncustom_user_agent: \"Cimian/1.0\"\n```\n\n### Configuration Management\n\n- **Interactive Setup**: Run `cimiimport.exe --config` for guided configuration\n- **Automatic Setup**: Use `cimiimport.exe --config-auto` for non-interactive configuration\n- **Validation**: Configuration is validated on startup with detailed error reporting\n\n## Manifests and Package Info Examples\n\n### Sample Manifest Files\n\nManifests define what software should be installed on specific groups of computers. They are stored in the `manifests/` directory of your repository.\n\n#### Basic Site Default Manifest (`manifests/site_default.yaml`)\n\n```yaml\nname: \"Site Default - Corporate Baseline\"\ncatalogs:\n  - Production\n\n# Base software for all systems\nmanaged_installs:\n  - Firefox\n  - GoogleChrome\n  - AdobeReader\n  - 7zip\n  - WindowsUpdates\n\n# Optional software available for installation\noptional_installs:\n  - VLCMediaPlayer\n  - GIMP\n  - NotePadPlusPlus\n\n# Software to remove if found\nmanaged_uninstalls:\n  - OldSoftware\n  - BloatwareApp\n```\n\n#### Advanced Conditional Manifest (`manifests/computer_groups/lab_computers.yaml`)\n\n```yaml\nname: \"Lab Computers - Educational Environment\"\ncatalogs:\n  - Testing\n  - Education\n\n# Base software for all lab computers\nmanaged_installs:\n  - BaseSecurityAgent\n  - StudentMonitoringSoftware\n  - SharedPrinterDrivers\n\n# Conditional software based on system facts\nconditional_items:\n  # Engineering labs get CAD software\n  - condition: \"hostname CONTAINS ENG-LAB\"\n    managed_installs:\n      - AutoCAD\n      - SolidWorks\n      - MATLAB\n    \n  # Art labs get creative software  \n  - condition: \"hostname CONTAINS ART-LAB\"\n    managed_installs:\n      - AdobeCreativeSuite\n      - Blender\n      - SketchUp\n      \n  # x64 systems get modern applications\n  - condition: \"arch == x64\"\n    managed_installs:\n      - ModernVideoEditor\n    managed_uninstalls:\n      - LegacyX86Software\n\n# Microsoft Intune integration\nmanaged_profiles:\n  - EducationalWiFiProfile\n  - StudentEmailProfile\n  \nmanaged_apps:\n  - \"Microsoft Teams\"\n  - \"Microsoft Office\"\n  - \"OneNote\"\n```\n\n#### Enterprise Manifest (`manifests/desktops.yaml`)\n\n```yaml\nname: \"Corporate Desktops\"\ncatalogs:\n  - Production\n  - Corporate\n\nmanaged_installs:\n  - EnterpriseAntivirus\n  - OfficeTools\n  - CorporateVPN\n\n# Complex conditional logic\nconditional_items:\n  # Executive desktops\n  - conditions:\n      - \"hostname BEGINSWITH EXEC\"\n      - \"domain == CORPORATE\"\n    condition_type: \"AND\"\n    managed_installs:\n      - ExecutiveSuite\n      - PremiumOfficeAddins\n      - VIPSupportTools\n      \n  # Developer machines\n  - condition: \"hostname CONTAINS DEV\"\n    managed_installs:\n      - VisualStudio\n      - GitForWindows\n      - DockerDesktop\n    optional_installs:\n      - AdvancedDebugger\n      - PerformanceProfiler\n      \n  # Domain join type specific software\n  - condition: \"joined_type == entra\"\n    managed_installs:\n      - EntraIDTools\n      - AzureADSync\n  - condition: \"joined_type == domain\"\n    managed_installs:\n      - TraditionalDomainTools\n```\n\n### Sample Package Info Files\n\nPackage info files define individual software packages and their installation details. They are stored in the `pkgsinfo/` directory.\n\n#### MSI Package Example (`pkgsinfo/Adobe/AdobeReader.yaml`)\n\n```yaml\nname: AdobeReader\ndisplay_name: \"Adobe Acrobat Reader DC\"\nidentifier: com.adobe.reader.dc\nversion: \"24.003.20054\"\ndescription: \"Adobe Acrobat Reader DC - Free PDF viewer\"\ncatalogs:\n  - Testing\n  - Production\ncategory: \"PDF Tools\"\ndeveloper: \"Adobe Inc.\"\n\n# Installation details\ninstaller:\n  type: msi\n  size: 245760000\n  location: Adobe/AcroRdrDC_2400320054_MUI.msi\n  hash: \"sha256:a1b2c3d4e5f6789...\"\n  product_code: \"{AC76BA86-7AD7-1033-7B44-AC0F074E4100}\"\n  upgrade_code: \"{AC76BA86-7AD7-1033-7B44-AC0F074E4100}\"\n\n# What files this package installs\ninstalls:\n  - type: file\n    path: \"C:\\Program Files\\Adobe\\Acrobat DC\\Reader\\AcroRd32.exe\"\n    md5checksum: \"d41d8cd98f00b204e9800998ecf8427e\"\n    version: \"24.003.20054\"\n\n# System requirements\nsupported_architectures:\n  - x64\n  - x86\nminimum_os_version: \"10.0.19041\"\nminimum_cimian_version: \"2026.05.01.0000\"  # skip on agents older than this build\nunattended_install: true\nunattended_uninstall: true\n```\n\n#### EXE Package with Scripts (`pkgsinfo/Development/VisualStudio.yaml`)\n\n```yaml\nname: VisualStudio\ndisplay_name: \"Microsoft Visual Studio Community 2022\"\nidentifier: com.microsoft.visualstudio.community.2022\nversion: \"17.8.3\"\ndescription: \"Microsoft Visual Studio Community 2022 - Free IDE\"\ncatalogs:\n  - Development\n  - Testing\ncategory: \"Development Tools\"\ndeveloper: \"Microsoft Corporation\"\n\n# EXE installer with custom arguments\ninstaller:\n  type: exe\n  size: 4294967296\n  location: Microsoft/VisualStudio/vs_community_2022.exe\n  hash: \"sha256:f8e7d6c5b4a39...\"\n  flags:\n    - quiet\n    - wait\n    - add Microsoft.VisualStudio.Workload.ManagedDesktop\n    - add Microsoft.VisualStudio.Workload.NetWeb\n\n# Installation tracking\ninstalls:\n  - type: file\n    path: \"C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\IDE\\devenv.exe\"\n    version: \"17.8.34316.72\"\n\n# Custom scripts\npreinstall_script: |\n  # Check system requirements\n  $ram = (Get-WmiObject -Class Win32_ComputerSystem).TotalPhysicalMemory / 1GB\n  if ($ram -lt 8) {\n    throw \"Visual Studio requires at least 8GB RAM\"\n  }\n  Write-Host \"System meets requirements\"\n\npostinstall_script: |\n  # Configure Visual Studio settings\n  $vsPath = \"${env:ProgramFiles}\\Microsoft Visual Studio\\2022\\Community\"\n  if (Test-Path $vsPath) {\n    Write-Host \"Visual Studio installed successfully\"\n    # Additional configuration here\n  }\n\n# Uninstaller\nuninstaller:\n  location: Microsoft/VisualStudio/vs_community_2022.exe\n  arguments:\n    - uninstall\n    - --quiet\n    - --wait\n\nsupported_architectures:\n  - x64\nminimum_os_version: \"10.0.17763\"\nminimum_cimian_version: \"2026.05.01.0000\"  # skip on agents older than this build\nunattended_install: true\nunattended_uninstall: true\n```\n\n#### PowerShell Script Package (`pkgsinfo/Scripts/SystemConfiguration.yaml`)\n\n```yaml\nname: SystemConfiguration\ndisplay_name: \"Corporate System Configuration\"\nidentifier: com.company.systemconfig\nversion: \"1.2.0\"\ndescription: \"Applies corporate system configuration settings\"\ncatalogs:\n  - Production\ncategory: \"System Configuration\"\ndeveloper: \"IT Department\"\n\n# PowerShell script installer\ninstaller:\n  type: ps1\n  size: 8192\n  location: Scripts/SystemConfiguration.ps1\n  hash: \"sha256:1a2b3c4d5e6f...\"\n\n# Script content (can also be external file)\npreinstall_script: |\n  # Backup current settings\n  $backupPath = \"C:\\Temp\\SystemBackup-$(Get-Date -Format 'yyyyMMdd-HHmmss')\"\n  New-Item -ItemType Directory -Path $backupPath -Force\n\npostinstall_script: |\n  # Verify configuration applied successfully\n  Write-Host \"System configuration completed\"\n  \n  # Set registry values\n  Set-ItemProperty -Path \"HKLM:\\SOFTWARE\\Company\\Config\" -Name \"LastUpdate\" -Value (Get-Date)\n\n# This is a script-only package - no file tracking needed\nsupported_architectures:\n  - x64\n  - arm64\n  - x86\nunattended_install: true\nunattended_uninstall: false  # Scripts can't be \"uninstalled\"\nOnDemand: false  # Run during normal update cycles\n```\n\n#### Complex Package with Dependencies (`pkgsinfo/Microsoft/Office365.yaml`)\n\n```yaml\nname: Office365\ndisplay_name: \"Microsoft 365 Apps for Enterprise\"\nidentifier: com.microsoft.office365.enterprise\nversion: \"16.0.17126.20132\"\ndescription: \"Microsoft 365 Apps for Enterprise suite\"\ncatalogs:\n  - Production\n  - Corporate\ncategory: \"Office Applications\"\ndeveloper: \"Microsoft Corporation\"\n\n# Complex installer with configuration\ninstaller:\n  type: exe\n  size: 6442450944\n  location: Microsoft/Office365/setup.exe\n  hash: \"sha256:9f8e7d6c5b4a3...\"\n  arguments:\n    - /configure\n    - /quiet\n    - /config:configuration.xml\n\n# Multiple file installations tracked\ninstalls:\n  - type: file\n    path: \"C:\\Program Files\\Microsoft Office\\root\\Office16\\WINWORD.EXE\"\n    version: \"16.0.17126.20132\"\n  - type: file  \n    path: \"C:\\Program Files\\Microsoft Office\\root\\Office16\\EXCEL.EXE\"\n    version: \"16.0.17126.20132\"\n  - type: file\n    path: \"C:\\Program Files\\Microsoft Office\\root\\Office16\\POWERPNT.EXE\" \n    version: \"16.0.17126.20132\"\n\n# Prerequisites and dependencies\nrequires:\n  - DotNetFramework48\n  - VisualCPPRedistributable\n\n# Advanced uninstall handling\nuninstaller:\n  type: exe\n  location: Microsoft/Office365/setup.exe\n  arguments:\n    - /configure\n    - /quiet\n    - /uninstall\n\nuninstalls:\n  - type: directory\n    path: \"C:\\Program Files\\Microsoft Office\"\n    recursive: true\n    force: true\n  - type: registry\n    path: \"HKLM\\SOFTWARE\\Microsoft\\Office\"\n    recursive: true\n\n# System requirements\nsupported_architectures:\n  - x64\nminimum_os_version: \"10.0.19041\"\nmaximum_os_version: \"\"\nminimum_cimian_version: \"2026.05.01.0000\"  # skip on agents older than this build\nunattended_install: true\nunattended_uninstall: true\n```\n\n## Conditional Items System\n\nCimian features a powerful conditional items system inspired by Munki's NSPredicate-style conditions, allowing dynamic software deployment based on system facts like hostname, architecture, domain membership, and more. The system supports complex expressions with OR/AND operators, nested conditional items for hierarchical logic, and both simple string format and structured conditions.\n\n### Simple String Format\n\nUse natural language patterns with `condition:` for complex expressions:\n\n```yaml\nconditional_items:\n  # Basic hostname exclusion\n  - condition: hostname DOES_NOT_CONTAIN \"Camera\"\n    managed_installs:\n      - StandardSoftware\n      \n  # Architecture-specific deployment\n  - condition: arch == \"x64\"\n    managed_installs:\n      - ModernApplication\n      \n  # Multiple values using IN operator\n  - condition: hostname IN \"LAB-01,LAB-02,LAB-03\"\n    managed_installs:\n      - LabSoftware\n```\n\n### Complex Expression Support\n\nThe conditional system supports complex OR/AND expressions within a single condition string:\n\n```yaml\nconditional_items:\n  # Complex OR expression in single condition\n  - condition: hostname CONTAINS \"Design-\" OR hostname CONTAINS \"Studio-\" OR hostname CONTAINS \"Edit-\"\n    managed_installs:\n      - CreativeApplications\n      - AdvancedTools\n      \n  # Complex AND expression with OS version\n  - condition: os_vers_major \u003e= 11 AND arch == \"x64\"\n    managed_installs:\n      - ModernApplications\n      - x64OptimizedTools\n      \n  # Mixed AND/OR with special operators\n  - condition: NOT hostname CONTAINS \"Kiosk\" AND (domain == \"CORP\" OR domain == \"EDU\")\n    managed_installs:\n      - EnterpriseApplications\n      \n  # Enrollment-based conditions (Enhanced)\n  - condition: enrolled_usage == \"Shared\" AND enrolled_area != \"Classroom\"\n    managed_installs:\n      - SharedWorkspaceTools\n```\n\n### Nested Conditional Items\n\nCreate hierarchical conditional logic with nested conditional items:\n\n```yaml\nconditional_items:\n  # Main condition with nested subconditions\n  - condition: enrolled_usage == \"Shared\"\n    conditional_items:\n      # Nested conditions within the main condition\n      - condition: enrolled_area != \"Classroom\" AND enrolled_area != \"Podium\"\n        managed_installs:\n          - CollaborativeTools\n          - GroupSoftware\n      \n      # Architecture-specific nested deployment\n      - condition: machine_type == \"desktop\"\n        conditional_items:\n          # Further nesting for granular control\n          - condition: os_vers_major \u003e= 11 AND arch == \"x64\"\n            managed_installs:\n              - HighEndApplications\n              - PerformanceTools\n        \n        managed_installs:\n          - BasicDesktopTools\n    \n    # Items for all machines matching the main condition\n    managed_installs:\n      - SharedMachineConfiguration\n      - SecurityHardening\n```\n\n### Legacy Multiple Conditions Format\n\nFor compatibility, the system still supports the legacy format with explicit `conditions` arrays:\n\n```yaml\nconditional_items:\n  # Legacy AND logic (prefer complex expressions)\n  - conditions:\n      - key: \"domain\"\n        operator: \"==\"\n        value: \"CORPORATE\"\n      - key: \"arch\" \n        operator: \"==\"\n        value: \"x64\"\n    condition_type: \"AND\"  # Default is AND\n    managed_installs:\n      - CorporateX64App\n      \n  # Legacy OR logic (prefer complex expressions)  \n  - conditions:\n      - key: \"hostname\"\n        operator: \"CONTAINS\"\n        value: \"DEV\"\n      - key: \"hostname\"\n        operator: \"CONTAINS\" \n        value: \"TEST\"\n    condition_type: \"OR\"\n    managed_installs:\n      - DeveloperTools\n```\n\n**Recommendation**: Use complex expressions instead:\n```yaml\nconditional_items:\n  # Preferred: Complex expression format\n  - condition: domain == \"CORPORATE\" AND arch == \"x64\"\n    managed_installs:\n      - CorporateX64App\n      \n  - condition: hostname CONTAINS \"DEV\" OR hostname CONTAINS \"TEST\"\n    managed_installs:\n      - DeveloperTools\n```\n\n### Supported Operators\n\n- **==** / **EQUALS**: Exact equality\n- **!=** / **NOT_EQUALS**: Not equal  \n- **CONTAINS**: String contains substring\n- **DOES_NOT_CONTAIN**: String does not contain substring\n- **BEGINSWITH**: String starts with value\n- **ENDSWITH**: String ends with value\n- **\u003e** / **\u003c** / **\u003e=** / **\u003c=**: Comparison operators (version-aware)\n- **IN**: Value is in a comma-separated list\n- **LIKE**: Wildcard pattern matching\n\n### Special Operators\n\n- **NOT**: Negates the following condition (e.g., `NOT hostname CONTAINS \"Kiosk\"`)\n- **OR**: Logical OR operator for complex expressions\n- **AND**: Logical AND operator for complex expressions\n\n\u003e **Note**: The ANY operator for array operations is planned for future implementation.\n\n### Available System Facts\n\n#### Core Facts\n- **hostname**: System hostname\n- **arch** / **architecture**: System architecture (x64, arm64, x86)\n- **os_version**: Windows OS version (full version string)\n- **os_vers_major**: Major OS version number (e.g., 10, 11)\n- **domain**: Windows domain name\n- **machine_type**: \"laptop\" or \"desktop\"\n- **machine_model**: Computer model\n- **joined_type**: \"domain\", \"hybrid\", \"entra\", or \"workgroup\"\n- **catalogs**: Available catalogs (array)\n- **username**: Current username\n- **date**: Current date and time\n\n#### Enhanced Facts\n- **enrolled_usage**: Device enrollment usage type (from registration or environment)\n- **enrolled_area**: Device enrollment area (from registration or environment) \n- **os_build_number**: Windows build number\n- **battery_state**: Battery state for mobile devices\n\n### Practical Examples\n\n#### Complex Enterprise Deployment\n```yaml\nconditional_items:\n  # Corporate environment with nested departmental logic\n  - condition: domain == \"CORPORATE\"\n    conditional_items:\n      # Executive desktops with complex hostname patterns\n      - condition: hostname CONTAINS \"EXEC-\" OR hostname CONTAINS \"C-SUITE-\" OR hostname CONTAINS \"BOARD-\"\n        managed_installs:\n          - ExecutiveSuite\n          - PremiumOffice\n          - VIPSupport\n          \n      # Development environment with role-based deployment\n      - condition: hostname CONTAINS \"DEV-\" OR hostname CONTAINS \"TEST-\"\n        conditional_items:\n          # Senior developers get additional tools\n          - condition: hostname CONTAINS \"SENIOR\" OR hostname CONTAINS \"LEAD\"\n            managed_installs:\n              - AdvancedDebugger\n              - PerformanceProfiler\n        \n        managed_installs:\n          - VisualStudio\n          - GitForWindows\n          - DockerDesktop\n    \n    # Base corporate software for all domain machines\n    managed_installs:\n      - EnterpriseAntivirus\n      - CorporateVPN\n      - ComplianceTools\n\n  # Educational shared machines\n  - condition: enrolled_usage == \"Shared\" AND enrolled_area != \"Classroom\"\n    managed_installs:\n      - CollaborativeTools\n      - SharedWorkspaceApps\n      - SecurityHardening\n\n  # High-performance desktops (complex requirements)\n  - condition: os_vers_major \u003e= 11 AND arch == \"x64\" AND NOT hostname CONTAINS \"Legacy\"\n    managed_installs:\n      - ModernApplications\n      - NextGenTools\n      - PerformanceOptimization\n```\n\n#### Architecture and OS Version Targeting\n```yaml\nconditional_items:\n  # Modern Windows 11 x64 systems only\n  - condition: os_vers_major \u003e= 11 AND arch == \"x64\"\n    managed_installs:\n      - Windows11OptimizedApps\n      - ModernWebApps\n      \n  # ARM64 specific applications\n  - condition: arch == \"arm64\"\n    managed_installs:\n      - ARMNativeApps\n    managed_uninstalls:\n      - x64OnlyLegacyApps\n      \n  # Exclude older systems from resource-intensive software\n  - condition: NOT (os_vers_major \u003c 11 OR arch == \"x86\")\n    managed_installs:\n      - ResourceIntensiveApps\n```\n\n### Best Practices\n\n#### 1. Use Complex Expressions Over Legacy Format\n**Preferred:**\n```yaml\n- condition: domain == \"CORPORATE\" AND arch == \"x64\"\n```\n\n**Instead of:**\n```yaml\n- conditions:\n    - key: \"domain\"\n      operator: \"==\"\n      value: \"CORPORATE\"\n    - key: \"arch\"\n      operator: \"==\"\n      value: \"x64\"\n  condition_type: \"AND\"\n```\n\n#### 2. Leverage Nested Conditionals for Organization\nUse nested conditional items to mirror your organizational structure and avoid redundant conditions.\n\n#### 3. Test Conditions Incrementally\nStart with simple conditions and build complexity:\n```yaml\n# Start simple\n- condition: hostname != \"\"\n  managed_installs: [TestPackage]\n\n# Add complexity gradually  \n- condition: hostname CONTAINS \"LAB\" OR hostname CONTAINS \"DEV\"\n  managed_installs: [TestPackage2]\n```\n\n#### 4. Performance Considerations\n- Place most restrictive conditions first\n- Use nested conditionals to reduce redundant fact evaluation\n- Order OR operations with most likely matches first\n\n### Debugging Conditional Items\n\n#### Check System Facts\nMonitor logs for \"System facts gathered\" entries to verify available facts.\n\n#### Validate Expression Parsing\nTest complex expressions with simple managed_installs items:\n```yaml\nconditional_items:\n  # Test parentheses parsing\n  - condition: (domain == \"CORP\" OR domain == \"EDU\") AND NOT hostname CONTAINS \"Kiosk\"\n    managed_installs: [ParenthesesTest]\n      \n  # Test OR/AND precedence\n  - condition: hostname CONTAINS \"A\" OR hostname CONTAINS \"B\" AND arch == \"x64\"\n    managed_installs: [PrecedenceTest]\n```\n\n## Monitoring and Logging\n\n### Event Logging\n\nCimian components write to Windows Event Log under:\n- **Application Log**: General application events\n- **System Log**: Service-related events  \n- **Custom Logs**: Detailed operation logs in `C:\\ProgramData\\ManagedInstalls\\logs\\`\n\n### Log Files\n\nCimian uses a modern structured logging system with timestamped session directories:\n\n| Component | Log Location | Purpose |\n|-----------|-------------|---------|\n| **Session Logs** | `C:\\ProgramData\\ManagedInstalls\\logs\\{YYYY-MM-DD-HHMMss}\\` | Individual session data with structured JSON and human-readable logs |\n| **Primary Log** | `C:\\ProgramData\\ManagedInstalls\\logs\\{session}\\install.log` | Human-readable installation operations log |\n| **Session Metadata** | `C:\\ProgramData\\ManagedInstalls\\logs\\{session}\\session.json` | Session start/end times, status, statistics |\n| **Event Stream** | `C:\\ProgramData\\ManagedInstalls\\logs\\{session}\\events.jsonl` | Detailed event tracking for troubleshooting |\n| **Summary Reports** | `C:\\ProgramData\\ManagedInstalls\\reports\\sessions.json` | Pre-computed session summaries for monitoring tools |\n| **Event Reports** | `C:\\ProgramData\\ManagedInstalls\\reports\\events.json` | Aggregated event data for analysis |\n| **CimianWatcher Service** | Windows Event Log (Application) | Service monitoring and bootstrap events |\n| **Status Runtime** | `C:\\ProgramData\\ManagedInstalls\\LastRunTime.txt` | Last execution timestamp |\n\n### Status Monitoring\n\nThe CimianStatus GUI provides real-time monitoring with:\n- **Installation Progress**: Visual progress bars and status updates\n- **Package Queue**: List of pending installations\n- **Error Reporting**: Detailed error messages and troubleshooting guidance  \n- **System Information**: Hardware, OS, and configuration details\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Service Not Running**: `sc start CimianWatcher`\n2. **Permission Issues**: Ensure Local System has access to repository paths\n3. **GUI Not Visible**: Check for Session 0 isolation in service environments\n4. **Package Import Failures**: Verify repository paths and write permissions\n5. **Network Connectivity**: Check repository URL and proxy settings\n\n### Diagnostic Tools\n\n```pwsh\n# Service status check\nGet-Service CimianWatcher\n\n# Process monitoring\ntasklist /fi \"imagename eq cimistatus.exe\"\n\n# Trigger diagnostic mode  \ncimitrigger.exe debug\n\n# Manual update check\nmanagedsoftwareupdate.exe --checkonly --verbose\n```\n\n## Enterprise Deployment\n\n### Microsoft Intune Integration\n\n1. **Package Creation**: Use `cimipkg.exe --nupkg --intunewin \u003cproject\u003e` to create .intunewin packages\n2. **Upload to Intune**: Import .intunewin files into Microsoft Endpoint Manager\n3. **Assignment**: Deploy to device groups with appropriate targeting\n4. **Monitoring**: Use Intune reporting for deployment status\n\n### Group Policy Integration\n\nDeploy Cimian configuration via Group Policy:\n- **Registry Settings**: Configure via Group Policy Preferences\n- **File Deployment**: Deploy config.yaml via Group Policy file copy\n- **Service Management**: Use Group Policy to manage service startup\n\n### SCCM Integration\n\nCimian can complement SCCM deployments:\n- **Package Distribution**: Use Cimian for rapid updates between SCCM cycles\n- **Self-Service**: Provide user-initiated software installation\n- **Reporting**: Centralized logging and status reporting\n\n## Performance and Scalability\n\n### Optimization Features\n\n- **Concurrent Downloads**: Configurable parallel download limits\n- **Delta Updates**: Only download changed package components\n- **Bandwidth Throttling**: Configurable download speed limits\n- **Retry Logic**: Automatic retry with exponential backoff\n- **Cache Management**: Intelligent local caching for frequently used packages\n\n### Scalability Metrics\n\n- **Clients per Repository**: Tested with 10,000+ concurrent clients\n- **Package Repository Size**: Supports multi-TB repositories\n- **Update Frequency**: Sub-minute update deployment capability\n- **Concurrent Operations**: Handles multiple simultaneous installations\n\n## Security Features\n\n### Code Signing\n\n- **Binary Signing**: All executables signed with enterprise certificates  \n- **Package Verification**: Automatic signature validation for imported packages\n- **PowerShell Signing**: Automatic script signing during package creation\n- **Certificate Management**: Automatic enterprise certificate detection\n\n### Security Hardening\n\n- **Privilege Elevation**: Minimal privilege escalation with automatic de-elevation\n- **Input Validation**: Comprehensive input sanitization and validation\n- **Secure Communications**: TLS encryption for repository communications\n- **Audit Logging**: Comprehensive audit trails for all operations\n\n### Compliance Features\n\n- **Change Tracking**: Full audit trail of software changes\n- **Approval Workflows**: Configurable approval processes for software deployment\n- **Compliance Reporting**: Built-in reporting for regulatory compliance\n- **Access Controls**: Role-based access control for administrative functions\n\n## License\n\nCimian is distributed under the MIT License. See [LICENSE](LICENSE) for details.\n\n## Contributing\n\nWe welcome contributions! Feel free to submit pull requests, report issues, or suggest improvements via our [GitHub repository](https://github.com/windowsadmins/cimian).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwindowsadmins%2Fcimian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwindowsadmins%2Fcimian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwindowsadmins%2Fcimian/lists"}