A Terraform module registry has to answer three things: a service discovery document that points to the module API, a list of versions per module, and a download endpoint that returns where the source lives. Anything that implements those can act as a registry for your teams.
The protocol in plain terms
HashiCorp documents the module registry protocol. The Terraform CLI uses remote service discovery, and the discovery document must expose a modules.v1 key whose value is the base URL for the other endpoints.
Two endpoints do the work:
| Endpoint | What it returns |
|---|---|
GET :namespace/:name/:system/versions | JSON with a modules array. The requested module goes first and each entry lists available versions. A 404 means no match. |
GET :namespace/:name/:system/:version/download | A 204 No Content response with an X-Terraform-Get header giving the source location. |
The download location can be a relative URL starting with /, ./ or ../. In other words, the registry does not have to host the code itself. It can point Terraform at a git repository or an archive.
Module addresses
A registry module address has the form hostname/namespace/name/system. The last segment is called "system" rather than "provider" in the protocol page. The hostname is optional and defaults to registry.terraform.io.
So a team can write a source such as registry.example.internal/platform/network/aws and add a version constraint. Version constraints work for registry modules, which is one reason to prefer a registry over bare git sources. See pinning Terraform modules.
Why a registry helps the security story
- A single catalogue. Teams look in one place for approved modules instead of copying code between repositories.
- Versions as first class objects. Constraints, ranges and upgrade commands work against the version list.
- Central ownership. The publisher decides which namespaces and names exist.
A registry does not make a module safe. It makes it findable and versioned. Review of what goes into it remains the control that counts.
What the protocol page does not tell you
The page I reviewed does not describe authentication, so I cannot say how a given registry should handle credentials. Terraform's separate guidance on credentials covers that, and your registry vendor's documentation covers the rest. For credential handling on the client side, see registry credentials and token variables.
It also says nothing about integrity checks for module contents. Treat the registry as a catalogue and add your own controls.
Questions to ask about your registry
- Who can publish a new version, and is publishing tied to review of the source repository?
- Can a published version be replaced or deleted, and who can do it?
- Does the download location point to an immutable reference such as a commit?
- Are publish and delete actions logged?
- How do you retire or deprecate a version?
Some of these depend on the product you choose, so check its documentation rather than assuming.
Where Safeguard fits
Safeguard can inventory dependencies with SBOM and dependency scanning and apply policies to pull requests that change them. It does not provide a module registry.
Quick check
Does the registry have to store the module code?
No. The download endpoint returns a header with the source location, which may be a relative URL or another address.
What is the hostname if I leave it out?
Per HashiCorp, the hostname is optional and defaults to registry.terraform.io.
Sources
Last reviewed: 19 October 2026.
