hardened-images: Instructions file for GitHub Copilot

Packer and Shell Provisioning Instructions

Apply these rules to Packer templates and the shell scripts that build and provision the hardened images.

Shell scripting requirements

• Start scripts with set -euo pipefail (or equivalent explicit error handling) so failures during a build stop the pipeline rather than continuing silently.
• Must pass shellcheck (enforced via .pre-commit-config.yaml, the shell job in .github/workflows/lint.yml, and build_box.sh itself); fix findings rather than disabling checks. When a suppression is genuinely correct, use a targeted # shellcheck disable=SCxxxx with a comment saying why.
• azure_vars_export is sourced, not executed. It must not use set -e, which would terminate the caller's interactive shell; it handles errors explicitly and returns instead.
• Quote variables and paths; avoid word-splitting/glob bugs on user-supplied input (e.g. -var overrides passed to build_box.sh).
• Never persist Azure ARM_* credentials or other secrets to disk; only export them into the current shell's environment.

Packer template requirements

• Keep *.pkr.hcl declarative — provisioning logic belongs in scripts/ or config/local.yml, not inline shell embedded in HCL.
• Pin required_version for Packer core and every entry in required_plugins to an exact minor series (~> 1.1.6), mirroring the existing templates. A floating >= constraint is not a pin.
• Templates must be packer fmt clean and must packer validate. Both are enforced by the packer job in .github/workflows/lint.yml, and build_box.sh runs packer validate before packer build.
• Mark credential variables sensitive = true unless the value is a short common word, which Packer would then redact from unrelated build output. State the reason in a comment when leaving one unmarked.
• Use variable ... validation blocks for values whose absence would otherwise produce a silently wrong build, such as the IP address that scopes the Azure build VM's inbound SSH rule.
• Provisioner scripts are #!/bin/bash and rely on bash-only behaviour, so execute_command must invoke bash, not sh.