feat(build): support mount symlink in terraform build (#8854)

* feat(build): support --mount-symlinks in terraform build

Thread the --mount-symlinks flag through the Terraform build pipeline so
that zip artifacts containing symlinks (e.g. absolute symlinks) can be
extracted during sam build --hook-name terraform.

Changes:
- copy_terraform_built_artifacts.py: Add --mount-symlinks CLI flag and
  pass it to unzip()
- makefile_generator.py: Include $(SAM_CLI_MOUNT_SYMLINKS_FLAG)
  placeholder in the Makefile recipe
- app_builder.py: Replace the placeholder with --mount-symlinks in the
  Makefile before invoking the builder (per-build, race-safe)
- build_integ_base.py: Add mount_symlinks parameter to get_command_list

Tests:
- Script-level tests for symlink zip extraction with/without flag
- E2E integration test with sam build --hook-name terraform
- Unit test for makefile recipe generation

* black

* change to pass mount-symlink down from the call chain

* feedback

Author: roger-zhangg

samcli/commands/_utils/custom_options/hook_name_option.py

@@ -90,6 +90,7 @@ def _call_prepare_hook(self, iac_hook_wrapper, opts, ctx):
             skip_prepare_infra = _read_parameter_value("skip_prepare_infra", opts, ctx, False)
             plan_file = _read_parameter_value("terraform_plan_file", opts, ctx)
             project_root_dir = _read_parameter_value("terraform_project_root_path", opts, ctx)
+            mount_symlinks = _read_parameter_value("mount_symlinks", opts, ctx, False)
 
             metadata_file = iac_hook_wrapper.prepare(
                 output_dir_path,
@@ -100,6 +101,7 @@ def _call_prepare_hook(self, iac_hook_wrapper, opts, ctx):
                 skip_prepare_infra,
                 plan_file,
                 project_root_dir,
+                mount_symlinks,
             )
 
             LOG.info("Prepare hook completed and metadata file generated at: %s", metadata_file)

samcli/hook_packages/terraform/copy_terraform_built_artifacts.py

@@ -218,7 +218,7 @@ def cli_exit():
     sys.exit(1)
 
 
-def find_and_copy_assets(directory_path, expression, data_object):
+def find_and_copy_assets(directory_path, expression, data_object, mount_symlinks=False):
     """
     Takes in an expression, directory_path and a json input from the standard input,
     tries to find the appropriate element within the json based on the element. It then takes action to
@@ -264,7 +264,7 @@ def find_and_copy_assets(directory_path, expression, data_object):
 
     try:
         if zipfile.is_zipfile(abs_attribute_path):
-            unzip(abs_attribute_path, directory_path)
+            unzip(abs_attribute_path, directory_path, mount_symlinks=mount_symlinks)
         else:
             copytree(abs_attribute_path, directory_path)
     except OSError as ex:
@@ -342,12 +342,19 @@ def validate_environment_variables():
         required=False,
         help="Terraform output json body. This option is not to be used with --target.",
     )
+    argparser.add_argument(
+        "--mount-symlinks",
+        action="store_true",
+        default=False,
+        help="Allow symlinks pointing outside the extraction directory when unzipping artifacts.",
+    )
 
     arguments = argparser.parse_args()
     directory_path = os.path.abspath(arguments.directory)
     expression = arguments.expression
     target = arguments.target
     json_str = arguments.json
+    mount_symlinks = arguments.mount_symlinks
 
     # validate environment variables do not contain blocked arguments
     validate_environment_variables()
@@ -384,4 +391,4 @@ def validate_environment_variables():
         cli_exit()
 
     LOG.info("Find and copy built assets")
-    find_and_copy_assets(directory_path, expression, data_object)
+    find_and_copy_assets(directory_path, expression, data_object, mount_symlinks=mount_symlinks)

samcli/hook_packages/terraform/hooks/prepare/enrich.py

@@ -52,6 +52,7 @@ def enrich_resources_and_generate_makefile(
     terraform_application_dir: str,
     lambda_resources_to_code_map: Dict,
     project_root_dir: str,
+    mount_symlinks: bool = False,
 ) -> None:
     """
     Use the sam metadata resources to enrich the mapped resources and to create a Makefile with a rule for
@@ -111,7 +112,12 @@ def enrich_resources_and_generate_makefile(
 
             # get makefile rule for resource
             makefile_rule = generate_makefile_rule_for_lambda_resource(
-                sam_metadata_resource, logical_id, terraform_application_dir, python_command_name, output_directory_path
+                sam_metadata_resource,
+                logical_id,
+                terraform_application_dir,
+                python_command_name,
+                output_directory_path,
+                mount_symlinks=mount_symlinks,
             )
             makefile_rules.append(makefile_rule)
 

samcli/hook_packages/terraform/hooks/prepare/hook.py

@@ -94,6 +94,7 @@ def prepare(params: dict) -> dict:
         LOG.debug("The normalized OutputDirPath value is %s", output_dir_path)
 
     skip_prepare_infra = params.get("SkipPrepareInfra", False)
+    mount_symlinks = params.get("MountSymlinks", False)
     metadata_file_path = os.path.join(output_dir_path, TERRAFORM_METADATA_FILE)
 
     plan_file = params.get("PlanFile")
@@ -112,7 +113,9 @@ def prepare(params: dict) -> dict:
 
             # convert terraform to cloudformation
             LOG.info("Generating metadata file")
-            cfn_dict = translate_to_cfn(tf_json, output_dir_path, terraform_application_dir, project_root_dir)
+            cfn_dict = translate_to_cfn(
+                tf_json, output_dir_path, terraform_application_dir, project_root_dir, mount_symlinks=mount_symlinks
+            )
 
             if cfn_dict.get("Resources"):
                 _update_resources_paths(cfn_dict.get("Resources"), terraform_application_dir)  # type: ignore

samcli/hook_packages/terraform/hooks/prepare/makefile_generator.py

@@ -29,6 +29,7 @@ def generate_makefile_rule_for_lambda_resource(
     terraform_application_dir: str,
     python_command_name: str,
     output_dir: str,
+    mount_symlinks: bool = False,
 ) -> str:
     """
     Generates and returns a makefile rule for the lambda resource associated with the given sam metadata resource.
@@ -56,7 +57,12 @@ def generate_makefile_rule_for_lambda_resource(
     resource_address = sam_metadata_resource.resource.get("address", "")
     python_command_recipe = _format_makefile_recipe(
         _build_makerule_python_command(
-            python_command_name, output_dir, resource_address, sam_metadata_resource, terraform_application_dir
+            python_command_name,
+            output_dir,
+            resource_address,
+            sam_metadata_resource,
+            terraform_application_dir,
+            mount_symlinks=mount_symlinks,
         )
     )
     return f"{target}{python_command_recipe}"
@@ -124,6 +130,7 @@ def _build_makerule_python_command(
     resource_address: str,
     sam_metadata_resource: SamMetadataResource,
     terraform_application_dir: str,
+    mount_symlinks: bool = False,
 ) -> str:
     """
     Build the Python command recipe to be used inside of the Makefile rule
@@ -155,12 +162,15 @@ def _build_makerule_python_command(
     terraform_built_artifacts_script_path = convert_path_to_unix_path(
         str(Path(output_dir, TERRAFORM_BUILD_SCRIPT).relative_to(terraform_application_dir))
     )
-    return show_command_template.format(
+    command = show_command_template.format(
         python_command_name=python_command_name,
         terraform_built_artifacts_script_path=terraform_built_artifacts_script_path,
         jpath_string=jpath_string.replace('"', '\\"'),
         resource_address=resource_address.replace('"', '\\"'),
     )
+    if mount_symlinks:
+        command += " --mount-symlinks"
+    return command
 
 
 def _get_makefile_build_target(logical_id: str) -> str:

samcli/hook_packages/terraform/hooks/prepare/translate.py

@@ -152,7 +152,11 @@ def _check_unresolvable_values(root_module: dict, root_tf_module: TFModule) -> N
 
 
 def translate_to_cfn(
-    tf_json: dict, output_directory_path: str, terraform_application_dir: str, project_root_dir: str
+    tf_json: dict,
+    output_directory_path: str,
+    terraform_application_dir: str,
+    project_root_dir: str,
+    mount_symlinks: bool = False,
 ) -> dict:
     """
     Translates the json output of a terraform show into CloudFormation
@@ -339,6 +343,7 @@ def translate_to_cfn(
             terraform_application_dir,
             lambda_resources_to_code_map,
             project_root_dir,
+            mount_symlinks=mount_symlinks,
         )
     else:
         LOG.debug("There is no sam metadata resources, no enrichment or Makefile is required")

samcli/lib/hook/hook_wrapper.py

@@ -54,6 +54,7 @@ def prepare(
         skip_prepare_infra: bool = False,
         plan_file: Optional[str] = None,
         project_root_dir: Optional[str] = None,
+        mount_symlinks: bool = False,
     ) -> str:
         """
         Run the prepare hook to generate the IaC Metadata file.
@@ -96,6 +97,8 @@ def prepare(
             params["PlanFile"] = plan_file
         if project_root_dir:
             params["ProjectRootDir"] = project_root_dir
+        if mount_symlinks:
+            params["MountSymlinks"] = mount_symlinks
 
         output = self._execute("prepare", params)
 

tests/integration/buildcmd/build_integ_base.py

@@ -114,6 +114,7 @@ def get_command_list(
         save_params=False,
         project_root_dir=None,
         use_buildkit=False,
+        mount_symlinks=False,
     ):
         command_list = [self.cmd, "build"]
 
@@ -189,6 +190,9 @@ def get_command_list(
         if project_root_dir is not None:
             command_list += ["--terraform-project-root-path", project_root_dir]
 
+        if mount_symlinks:
+            command_list += ["--mount-symlinks"]
+
         return command_list
 
     def verify_docker_container_cleanedup(self, runtime):

tests/integration/buildcmd/test_build_terraform_applications.py

@@ -435,3 +435,57 @@ def test_build_and_invoke_lambda_functions(self):
                 "multiValueHeaders": None,
             },
         )
+
+
+@skipIf(
+    (not RUN_BY_CANARY and not CI_OVERRIDE),
+    "Skip Terraform test cases unless running in CI",
+)
+class TestBuildTerraformWithSymlinkZip(BuildTerraformApplicationIntegBase):
+    """Test sam build --hook-name terraform with a zip artifact containing symlinks."""
+
+    terraform_application = Path("terraform/zip_with_symlink")
+    function_identifier = "aws_lambda_function.symlink_function"
+
+    def setUp(self):
+        # Call grandparent setUp (BuildIntegBase) for working_dir setup, then copy terraform project.
+        # Skip BuildTerraformApplicationIntegBase.setUp which calls build_with_prepare_hook().
+        BuildIntegBase.setUp(self)
+        shutil.rmtree(Path(self.working_dir))
+        shutil.copytree(Path(self.terraform_application_path), Path(self.working_dir))
+
+    def _run_build(self, mount_symlinks=False):
+        build_cmd = self.get_command_list(
+            function_identifier=self.function_identifier,
+            hook_name="terraform",
+            mount_symlinks=mount_symlinks,
+        )
+        LOG.info("Running: %s", " ".join(build_cmd))
+        return self.run_command(build_cmd)
+
+    def test_build_fails_without_mount_symlinks(self):
+        """Build should fail when zip contains absolute symlink and --mount-symlinks is not set."""
+        _, stderr, returncode = self._run_build(mount_symlinks=False)
+        stderr_str = stderr.decode("utf-8") if isinstance(stderr, bytes) else stderr
+        self.assertNotEqual(returncode, 0, f"Expected build to fail but it succeeded. stderr: {stderr_str}")
+        self.assertIn(
+            "Failed to extract file from the zip file. A symlink has an absolute target which is not allowed",
+            stderr_str,
+        )
+
+    def test_build_succeeds_with_mount_symlinks(self):
+        """Build should succeed when zip contains absolute symlink and --mount-symlinks is set."""
+        _, stderr, returncode = self._run_build(mount_symlinks=True)
+        stderr_str = stderr.decode("utf-8") if isinstance(stderr, bytes) else stderr
+        self.assertEqual(returncode, 0, f"Expected build to succeed but it failed. stderr: {stderr_str}")
+
+        # Find the function build directory (SAM CLI generates a hashed logical ID)
+        build_dir = Path(self.working_dir) / ".aws-sam" / "build"
+        self.assertTrue(build_dir.exists(), f"Build output directory not found: {build_dir}")
+        function_dirs = [d for d in build_dir.iterdir() if d.is_dir()]
+        self.assertEqual(len(function_dirs), 1, f"Expected 1 function dir, found: {function_dirs}")
+
+        function_dir = function_dirs[0]
+        symlink_path = function_dir / "external_link"
+        self.assertTrue(symlink_path.is_symlink(), f"Expected symlink at {symlink_path}")
+        self.assertEqual(os.readlink(str(symlink_path)), "/tmp/some_external_target")

tests/integration/scripts/test_copy_terraform_built_artifacts.py

@@ -200,3 +200,60 @@ def test_script_output_path_invalid_json(self):
             subprocess.check_call(
                 command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, stdin=subprocess.PIPE, cwd=self.working_dir
             )
+
+    def test_script_zip_with_symlink_fails_without_mount_symlinks(self):
+        """Test that unzipping a zip with an absolute symlink fails by default."""
+        input_file = self.testdata_directory.joinpath("build-output-path-symlink-zip.json")
+        with open(input_file, "rb") as f:
+            json_str = f.read().decode("utf-8")
+        command = [
+            str(sys.executable),
+            str(self.script_location),
+            "--directory",
+            str(self.directory),
+            "--expression",
+            self.expression,
+            "--json",
+            json_str,
+        ]
+        env = os.environ.copy()
+        with self.assertRaises(subprocess.CalledProcessError) as ctx:
+            subprocess.check_output(
+                command,
+                stderr=subprocess.STDOUT,
+                stdin=subprocess.PIPE,
+                cwd=self.working_dir,
+                env=env,
+            )
+        self.assertIn(
+            "Failed to extract file from the zip file. A symlink has an absolute target which is not allowed",
+            ctx.exception.output.decode("utf-8"),
+        )
+
+    def test_script_zip_with_symlink_succeeds_with_mount_symlinks(self):
+        """Test that unzipping a zip with an absolute symlink succeeds when --mount-symlinks is passed."""
+        input_file = self.testdata_directory.joinpath("build-output-path-symlink-zip.json")
+        with open(input_file, "rb") as f:
+            json_str = f.read().decode("utf-8")
+        command = [
+            str(sys.executable),
+            str(self.script_location),
+            "--directory",
+            str(self.directory),
+            "--expression",
+            self.expression,
+            "--json",
+            json_str,
+            "--mount-symlinks",
+        ]
+        subprocess.check_call(
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            stdin=subprocess.PIPE,
+            cwd=self.working_dir,
+        )
+        # Verify the symlink was created
+        link_path = os.path.join(self.directory, "external_link")
+        self.assertTrue(os.path.islink(link_path))
+        self.assertEqual(os.readlink(link_path), "/tmp/external_target")