@hoiltd/azure-marketplace-generator

v3.1.2

Published

6 months ago

CLI tool for generating Azure Storage marketplace managed applications with enhanced security and data protection features

0High
0Medium
0Low

msalsouri

azure marketplace managed-applications arm-templates partner-center azure-storage cli typescript security data-protection

Azure Marketplace Generator

Enterprise-grade CLI tool for generating Azure Storage marketplace managed applications with comprehensive security and data protection features.

Features

Core Capabilities

Storage-focused managed application generation with production-ready templates
ARM template validation with Microsoft ARM-TTK integration
Marketplace-ready package creation for Azure Marketplace submission
TypeScript with full type safety for reliability and maintainability
Extensible plugin architecture for custom templates and commands (v3.1.0 - [OK] Fully Operational)
- Install plugins from npm or use local plugins
- Extend with custom Handlebars helpers
- Add CLI commands dynamically
- First official plugin: @hoiltd/[email protected] - [OK] 98% ARM-TTK Compliance

Enhanced Security Features (v3.0.0)

Blob Public Access Control - Prevent anonymous access to blobs
TLS Version Enforcement - Require minimum TLS 1.2 for all connections
HTTPS-Only Traffic - Enforce secure transport for all requests
Public Network Access Control - Restrict access to selected networks
OAuth Default Authentication - Prioritize Microsoft Entra ID (Azure AD) authentication
Shared Key Access Management - Disable legacy shared key authentication
Infrastructure Encryption - Double encryption for data at rest

️ Data Protection Features (v3.0.0)

Blob Soft Delete - Configurable retention (7-365 days) for deleted blobs
Container Soft Delete - Configurable retention (7-365 days) for deleted containers
Blob Versioning - Automatic version tracking for blob modifications
Change Feed - Ordered transaction log for all changes
Last Access Time Tracking - Monitor and optimize storage costs

Note: All parameters are verified against official Microsoft Azure documentation for production compliance.

Installation

From NPM (Recommended)

# Install globally
npm install -g @hoiltd/azure-marketplace-generator

# Verify installation
azmp --version

From Source

# Clone and install
git clone https://github.com/HOME-OFFICE-IMPROVEMENTS-LTD/azure-marketplace-generator.git
cd azure-marketplace-generator
npm install

# Install ARM-TTK for validation
npm run install-arm-ttk

# Build the CLI
npm run build

Quick Links

NPM Package - Install the latest version
GitHub Wiki - Comprehensive guides and tutorials
Releases - Version history and changelogs
Discussions - Community support and ideas
Issues - Bug reports and feature requests
Plugin: VM - Virtual Machine plugin (@hoiltd/[email protected]) - [OK] Marketplace Certified

Usage

Create Storage Solution

azmp create storage --publisher "MyCompany" --name "MyStorageApp"

Generated templates include:

[OK] All security parameters (7) configured with secure defaults
[OK] All data protection features (5) with recommended settings
[OK] Production-ready ARM templates validated against Azure specifications
[OK] UI definitions with intuitive configuration steps

For detailed parameter configuration, see SECURITY_FEATURES.md and DATA_PROTECTION_GUIDE.md.

Validate Templates

azmp validate ./output

Package for Marketplace

azmp package ./output

Commands

| Command | Description | |---------|-------------| | azmp create storage | Create new storage managed application | | azmp validate <path> | Validate ARM templates with ARM-TTK | | azmp package <path> | Package templates for marketplace submission |

Output Structure

output/
--- mainTemplate.json          # ARM template
--- createUiDefinition.json    # UI definition  
--- viewDefinition.json        # Management view
--- nestedtemplates/           # Nested templates
    --- storageAccount.json

Samples

Canonical reference templates (for comparison, testing, and authoring) are now stored under the samples/ directory:

samples/
--- storage/        # Canonical storage managed application (mainTemplate, createUiDefinition, viewDefinition)
--- vm/             # Reference VM sample from plugin (not generated in core mode)

Use these samples to:

Quickly diff future template changes against a known-good baseline
Validate ARM-TTK regression behavior without invoking the generator
Prototype enhancements before wiring them into Handlebars templates

Removed Debug Fixtures

Legacy experimental folders test-debug/ and test-debug-no-gallery/ have been removed to keep the repository lean. Their advanced configuration patterns (security, data protection, optional service/event features) are fully represented in samples/storage/. If you need to experiment with stripped-down variants (e.g. without gallery metadata), duplicate samples/storage/createUiDefinition.json and remove the gallery block—no other changes required.

Rationale for removal:

Eliminated duplicate template parameter sets
Reduced cognitive overhead for contributors
Ensured a single canonical advanced storage baseline

If a future minimal “basic” sample is required, it can be derived from the current storage sample by removing the serviceSelection and eventGridSection steps plus related parameters and outputs.

Core-Only Mode (Plugin Disabled)

The repository defaults to a "core-only" mode for smoke testing by disabling the VM plugin in azmp.config.json:

{
  "plugins": [
    {
      "package": "/home/msalsouri/Projects/azmp-plugin-vm/dist",
      "enabled": false
    }
  ]
}

Re‑enable the plugin by setting enabled: true or adding additional plugin entries. In core-only mode, only built-in storage generation commands are available which keeps the validation surface minimal and fast.

Smoke Test

A Jest smoke test (src/__tests__/smoke-core.test.ts) exercises the full core pipeline:

Build the CLI
Generate a storage application
Validate with ARM‑TTK
Package into a zip

Run it directly:

npm run build
npx jest src/__tests__/smoke-core.test.ts

This test is intentionally minimal and avoids plugin dependency to keep CI fast and isolate core regressions.

Partner Center Preflight Validation

Before you upload a package to Azure Partner Center, you can run a deeper structural validation that simulates common certification checks.

We added a dedicated test (src/__tests__/listing-validation.test.ts) that verifies:

| Check | Purpose | |-------|---------| | Core file presence | Ensures mainTemplate.json, createUiDefinition.json, viewDefinition.json exist | | Parameter coverage | Confirms all 16 storage, security, and data protection parameters are declared | | Resource topology | Validates storage account + blobServices resources and dependency chain | | UI outputs mapping | Ensures every required parameter is exported from createUiDefinition.json | | View definitions | Confirms security & data protection status outputs are referenced in viewDefinition.json |

Run it directly:

npx jest src/__tests__/listing-validation.test.ts

Manual Partner Center Checklist

Generate package:

azmp create storage -p "Your Publisher" -n "Your Offer Name" -o ./output
azmp validate ./output   # (Optional but recommended – ARM-TTK)
azmp package ./output -o offer-v1.zip

Inspect ZIP contents (must contain exactly the three core JSON files unless you add nested templates):

unzip -l offer-v1.zip

Open mainTemplate.json and verify:

$schema points to deploymentTemplate.json
At least one resource of type Microsoft.Storage/storageAccounts
Parameters align to pricing/config tiers you intend to expose

Open createUiDefinition.json and confirm:

$schema uses the preview or current schema URL
gallery section exists (unless intentionally removed for private preview)
Every parameter needed by the template appears in parameters.outputs

Open viewDefinition.json and ensure:

Overview + Properties + Metrics sections present
Security/Data Protection references resolve to outputs (no typos)

Upload ZIP to Partner Center offer technical configuration
Use Preview to deploy internally (test with production subscription)
Capture deployment success evidence (screenshots, deployment JSON) for certification notes

Tip: If you need a gallery‑less variant for private preview, remove the gallery block from createUiDefinition.json after generation – no other changes required.

Package Artifact Policy

To keep the repository lean and reproducible:

Root-level ZIP files produced by azmp package are transient and should not be committed.
The .gitignore rules ignore all *.zip except curated, versioned examples stored under marketplace-packages/.
Curated samples (e.g. storage-offer-v1.0.zip) demonstrate expected package contents; regenerate others locally as needed.
If you create a new canonical sample, place it in marketplace-packages/ with a semantic version in the filename and update this section.

Rationale: Prevent stale or ambiguous artifacts, encourage deterministic regeneration, and reduce merge noise.

Packaging Output Filename Precedence

When running azmp package <path> the tool selects the output ZIP file name using a clear precedence order:

CLI argument -o, --output <file> (highest precedence)
packaging.defaultFileName from azmp.config.json (if provided and CLI flag omitted)
Built-in fallback: managed-app-package.zip

Examples:

# Uses explicit CLI value
azmp package ./output -o my-offer-v1.zip

# Uses config defaultFileName if defined
azmp package ./output --config ./azmp.config.json

# Falls back to built-in default if neither CLI nor config provides a name
azmp package ./output

Minimal azmp.config.json snippet:

{
  "packaging": {
    "defaultFileName": "my-default-package.zip"
  }
}

Tip: Avoid committing generated ZIPs—use the precedence system to keep builds reproducible.

Requirements

Node.js 18+
PowerShell (for ARM-TTK validation)

Development

# Run in development mode
npm run dev

# Run tests  
npm test

# Lint code
npm run lint

Documentation

References User Guides

Configuration Guide - Learn how to use config files for consistent settings
Security Features - Comprehensive guide to all 7 security parameters
Data Protection Guide - Complete guide to data protection features and recovery

Fixes Developer Resources

Production Features - Summary of all production-ready enhancements
Development Log - Version history and development phases
Changelog - Detailed changelog following Keep a Changelog format
Azure Live Testing - Comprehensive Azure deployment testing guide
Plugin Architecture - Extensibility framework for custom templates (v3.0.0+)

Official Resources

Roadmap

[OK] v3.0.0 (Released - October 2024)

[OK] Plugin interface foundation
[OK] 12 security and data protection parameters
[OK] Comprehensive documentation (9 guides)
[OK] Full Azure live testing (35/35 tests)

[OK] v3.1.0 (Released - December 2024)

Plugin System Implementation:

[OK] Plugin loader with dynamic discovery
[OK] Automatic plugin registration from config files
[OK] CLI command extensions support
[OK] Template type registration API
[OK] Handlebars helper registration API
[OK] Security validations (path traversal, workspace protection)
[OK] Conflict detection for helpers, commands, templates
[OK] Error isolation and timeout handling
[OK] Comprehensive test suite (119 tests passing)
[OK] Published to NPM registry
[OK] GitHub Actions security hardening (CodeQL alerts fixed)

Official Plugin Available:

@hoiltd/[email protected] - Virtual Machine plugin with comprehensive Azure VM support

Latest: v2.1.0 (October 31, 2025)

[OK] 98% ARM-TTK Compliance (46/47 tests passing)
[OK] Marketplace Certified - Production-ready templates
[OK] 801 passing tests (92% of 872 total test suite)
[OK] 178 Handlebars helpers for advanced template generation
[OK] 44 CLI commands for VM configuration
Features: VM sizes, OS images, networking, security, identity, HA, backup, monitoring

Installation:

npm install @hoiltd/azmp-plugin-vm@^2.1.0

Configuration Example:

{
  "plugins": [
    {
      "package": "@hoiltd/azmp-plugin-vm",
      "enabled": true,
      "options": {
        "defaultVmSize": "Standard_D2s_v3",
        "security": {
          "enableTrustedLaunch": true
        }
      }
    }
  ]
}

Resources:

v3.2.0 (In Development)

Core Improvements:

[ ] Semver validation for plugin versions
[ ] Eager template validation on plugin load
[ ] Plugin performance optimizations
[ ] Enhanced error messages and debugging

Plugin Ecosystem:

[ ] Plugin documentation improvements
[ ] Plugin testing utilities
[ ] Community plugin registry

Storage Features:

[ ] Private endpoint configuration
[ ] Customer-managed encryption keys (CMK)
[ ] Immutability policies for compliance
[ ] Advanced network security rules
[ ] Azure AD RBAC role assignments
[ ] Diagnostic settings and monitoring

Future Releases

Q1 2026: Compliance & Policy Guardrails Plugin

️ Enterprise Compliance Made Effortless

Next generation plugin for automatic governance and compliance frameworks:

Core Features:

One-click compliance frameworks (CIS, NIST 800-53, Azure Security Benchmark)
Automatic security baselines with Defender for Cloud integration
Checklist Policy as Code with pre-built Azure Policy initiatives
Alert Continuous monitoring with compliance dashboards and alerting
Matrix Compliance evidence generation for Partner Center submissions

Enterprise Value:

Enterprise trust - Built-in governance reduces security concerns
Premium pricing - Compliance commands higher deal values
Customer retention - Governance creates switching costs
Competitive advantage - Most marketplace tools ignore compliance

Target Frameworks:

CIS Azure Foundations Benchmark (Level 1 & 2)
NIST 800-53 (Moderate/High impact controls)
Azure Security Benchmark (Microsoft official baseline)
ISO 27001 Information Security Management
Industry-specific: HIPAA, PCI DSS, FedRAMP, GDPR

# Example usage
azmp create vm-solution --compliance=cis-level1
azmp create vm-solution --compliance=nist-800-53
azmp create storage --compliance=azure-security-benchmark

Full Proposal - Detailed technical specifications and implementation roadmap

Advanced Extensibility:

[ ] MCP (Model Context Protocol) server support
[ ] Remote plugin loading from registries
[ ] Plugin security scanning and verification
[ ] Advanced plugin APIs and lifecycle management
[ ] Plugin performance monitoring