Terraform Git SSH Module Download Fixer

Threat/Impact Level: HIGH | Exploitability/Downtime Risk: HIGH | Time to Fix: 10–20 mins

TL;DR

• What broke: Terraform's go-getter library cannot complete an SSH handshake to your Git remote when downloading a source module — caused by a missing SSH key, unverified host fingerprint, wrong URL scheme, or a blocking Git credential helper.
• How to fix it: Verify your SSH key is loaded in the agent, the remote host is in ~/.ssh/known_hosts, and your module source uses the correct git::ssh:// or git@ syntax with a deploy key that has repo read access.
• Shortcut: Use the Client-Side Sandbox above to paste your failing module {} block and SSH config — it auto-refactors the source URL and generates the corrected git config and ssh-add commands without sending your keys anywhere.

Initializing modules...
╷
│ Error: Failed to download module
│
│   on main.tf line 12, in module "vpc":
│   12:   source = "git@github.com:corp/private-infra-modules.git//vpc?ref=v2.1.0"
│
│ Could not download module "vpc" (main.tf:12) source code from
│ "git::ssh://git@github.com/corp/private-infra-modules.git//vpc?ref=v2.1.0":
│ error downloading 'ssh://git@github.com/corp/private-infra-modules.git//vpc?ref=v2.1.0':
│ /usr/bin/git exited with 128: Host key verification failed.
│ fatal: Could not read from remote repository.
│
│ Please make sure you have the correct access rights
│ and the repository exists.
╵

How to Fix It (The Solution)

Diagnosis Checklist — Run These First

# 1. Is the SSH agent running and is your key loaded?
ssh-add -l

# 2. Can you reach the Git host at all?
ssh -T git@github.com
# Expected: "Hi username! You've successfully authenticated..."

# 3. Is the host in known_hosts?
ssh-keygen -F github.com

# 4. Check for conflicting gitconfig rewrites
git config --global --list | grep insteadOf

Fix 1: Host Key Not in known_hosts (Most Common)

The error: Host key verification failed

# Securely add the host fingerprint — verify it matches GitHub's published fingerprint
# https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints
ssh-keyscan -H github.com >> ~/.ssh/known_hosts

# Verify the fingerprint BEFORE trusting it
ssh-keygen -lf ~/.ssh/known_hosts | grep github.com
# Must match: SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s (RSA)

For CI runners (GitHub Actions):

- # No known_hosts setup — runner fails on first SSH contact
+ - name: Add GitHub to known_hosts
+   run: |
+     mkdir -p ~/.ssh
+     ssh-keyscan -H github.com >> ~/.ssh/known_hosts
+     chmod 600 ~/.ssh/known_hosts

Fix 2: SSH Key Not Loaded in Agent

- # Key exists on disk but ssh-add was never called
- # ssh-add -l returns: "The agent has no identities."

+ eval "$(ssh-agent -s)"
+ ssh-add ~/.ssh/id_ed25519_terraform_deploy
+ # Verify
+ ssh-add -l

Fix 3: Incorrect Module Source URL Scheme

Terraform go-getter requires a specific syntax. The [email protected]:org/repo.git SCP-style shorthand works in native Git but can break go-getter's URL parser in edge cases.

  module "vpc" {
-   source = "git@github.com:corp/private-infra-modules.git//vpc?ref=v2.1.0"
+   source = "git::ssh://git@github.com/corp/private-infra-modules.git//vpc?ref=v2.1.0"
    version = "~> 2.1"
  }

Note: The double-slash // is the go-getter subdirectory separator. It is not a typo.

Fix 4: Corporate gitconfig `insteadOf` Rewrite Conflict

If your org forces HTTPS for all Git operations:

# This is the killer — it rewrites ssh:// to https:// and breaks go-getter
git config --global url."https://".insteadOf git://

# Option A: Remove the global rewrite (if you control the machine)
- [url "https://"]
-     insteadOf = git://

# Option B: Add a scoped override just for your Git host
+ [url "git::ssh://git@github.com/"]
+     insteadOf = git@github.com:

Or set this per-repo in your pipeline environment:

- # No git config override — corporate insteadOf breaks go-getter
+ - name: Override git insteadOf for Terraform SSH modules
+   run: git config --global url."git::ssh://git@github.com/".insteadOf "git@github.com:"

Enterprise Best Practice: Scoped Deploy Key + SSH Config File

Never use a personal SSH key in CI. Use a read-only deploy key scoped to the specific repository.

Step 1: Generate a dedicated deploy key

ssh-keygen -t ed25519 -C "terraform-ci-deploy-key" -f ~/.ssh/terraform_deploy_ed25519 -N ""
# Add the PUBLIC key to GitHub repo → Settings → Deploy Keys → Read Only
cat ~/.ssh/terraform_deploy_ed25519.pub

Step 2: Configure SSH to use it only for this host alias

# ~/.ssh/config
+ Host github-terraform
+   HostName github.com
+   User git
+   IdentityFile ~/.ssh/terraform_deploy_ed25519
+   IdentitiesOnly yes
+   StrictHostKeyChecking yes

Step 3: Update the module source to use the alias

  module "vpc" {
-   source = "git::ssh://git@github.com/corp/private-infra-modules.git//vpc?ref=v2.1.0"
+   source = "git::ssh://git@github-terraform/corp/private-infra-modules.git//vpc?ref=v2.1.0"
  }

Step 4: Inject the private key in CI as a secret (GitHub Actions)

+ - name: Configure SSH deploy key for Terraform modules
+   env:
+     SSH_PRIVATE_KEY: ${{ secrets.TERRAFORM_MODULE_DEPLOY_KEY }}
+   run: |
+     mkdir -p ~/.ssh
+     echo "$SSH_PRIVATE_KEY" > ~/.ssh/terraform_deploy_ed25519
+     chmod 600 ~/.ssh/terraform_deploy_ed25519
+     ssh-keyscan -H github.com >> ~/.ssh/known_hosts
+     chmod 600 ~/.ssh/known_hosts

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

pip install checkov
checkov -d . --check CKV_GIT_1

# checkov/custom/terraform_ssh_source_check.py
from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck

class TerraformModuleSSHSourceCheck(BaseResourceCheck):
    def __init__(self):
        name = "Ensure Terraform module SSH sources use deploy key host aliases"
        id = "CKV_CUSTOM_TF_SSH_001"
        ...

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: terraform-ssh-check
      name: Validate Terraform SSH module connectivity
      entry: bash -c 'ssh -T git@github.com 2>&1 | grep -q "successfully authenticated" || (echo "SSH auth to GitHub failed. Run: ssh-add ~/.ssh/terraform_deploy_ed25519" && exit 1)'
      language: system
      pass_filenames: false

- # No SSH key mount — Atlantis pod fails terraform init
+ volumeMounts:
+   - name: terraform-ssh-key
+     mountPath: /home/atlantis/.ssh
+     readOnly: true
+ volumes:
+   - name: terraform-ssh-key
+     secret:
+       secretName: terraform-deploy-key
+       defaultMode: 0600

# policy/terraform_module_ref.rego
package terraform.modules

deny[msg] {
  mod := input.module[_]
  source := mod.source
  contains(source, "git::ssh://")
  not contains(source, "?ref=")
  msg := sprintf("Module source '%v' must pin a ref tag. Use ?ref=vX.Y.Z", [source])
}

conftest test main.tf --policy policy/