fix(repos): disclose dereferenced symlink reads

Detect internal symlink dereferences from Git blob identity mismatches, disclose explicit links and submodules, and preserve requested-path resource output. Use bounded exact-path tree inspection only when inline content is unavailable.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

pkg/github/repositories.go

@@ -1071,23 +1071,48 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool
 				if fallbackUsed {
 					successNote = fmt.Sprintf(" Note: the provided ref '%s' does not exist, default branch '%s' was used instead.", originalRef, rawOpts.Ref)
 				}
+				const maxContentSize = 1024 * 1024 // 1MB
+
+				inspection, respInspect, err := inspectRepositoryFile(ctx, client, owner, repo, ref, path, fileContent)
+				if err != nil {
+					if respInspect != nil {
+						return ghErrors.NewGitHubAPIErrorResponse(ctx,
+							"failed to inspect repository file",
+							respInspect,
+							err,
+						), nil, nil
+					}
+					return utils.NewToolResultError(fmt.Sprintf("failed to inspect repository file: %s", err)), nil, nil
+				}
+				if inspection.Submodule != nil {
+					return attachIFC(utils.NewToolResultText(marshalRepositorySubmoduleMetadata(inspection.Submodule))), nil, nil
+				}
+				if inspection.Symlink != nil &&
+					!inspection.ContentAvailable &&
+					(inspection.Symlink.Explicit || fileSize < maxContentSize) {
+					return attachIFC(utils.NewToolResultText(marshalRepositorySymlinkMetadata(
+						inspection.Symlink,
+						unavailableSymlinkContents,
+						successNote,
+					))), nil, nil
+				}
 
-				// Empty files (0 bytes) have no content to decode; return
-				// them directly as empty text to avoid errors from
-				// GetContent when the API returns null content with a
-				// base64 encoding field, and to avoid DetectContentType
-				// misclassifying them as binary.
-				if fileSize == 0 {
+				// Empty files are returned as empty text to avoid
+				// DetectContentType misclassifying them as binary.
+				if fileSize == 0 && inspection.ContentAvailable {
 					result := &mcp.ResourceContents{
 						URI:      resourceURI,
 						Text:     "",
 						MIMEType: "text/plain",
 					}
-					return attachIFC(utils.NewToolResultResource(fmt.Sprintf("successfully downloaded empty file (SHA: %s)%s", fileSHA, successNote), result)), nil, nil
+					message := fmt.Sprintf("successfully downloaded empty file (SHA: %s)%s", fileSHA, successNote)
+					if inspection.Symlink != nil {
+						message = marshalRepositorySymlinkMetadata(inspection.Symlink, dereferencedContentLabel, successNote)
+					}
+					return attachIFC(utils.NewToolResultResource(message, result)), nil, nil
 				}
 
 				// For files >= 1MB, return a ResourceLink instead of content
-				const maxContentSize = 1024 * 1024 // 1MB
 				if fileSize >= maxContentSize {
 					size := int64(fileSize)
 					resourceLink := &mcp.ResourceLink{
@@ -1096,22 +1121,28 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool
 						Title: fmt.Sprintf("File: %s", path),
 						Size:  &size,
 					}
+					message := fmt.Sprintf("File %s is too large to display (%d bytes). Use the download URL to fetch the content: %s (SHA: %s)%s",
+						path, fileSize, fileContent.GetDownloadURL(), fileSHA, successNote)
+					if inspection.Symlink != nil {
+						targetPath := inspection.Symlink.ResolvedTargetPath
+						if targetPath == "" {
+							targetPath = inspection.Symlink.Target
+						}
+						resourceLink.Title = fmt.Sprintf("Dereferenced target %s via symlink %s", targetPath, path)
+						message = marshalRepositorySymlinkMetadata(inspection.Symlink, dereferencedContentLabel, successNote)
+					}
 					return attachIFC(utils.NewToolResultResourceLink(
-						fmt.Sprintf("File %s is too large to display (%d bytes). Use the download URL to fetch the content: %s (SHA: %s)%s",
-							path, fileSize, fileContent.GetDownloadURL(), fileSHA, successNote),
+						message,
 						resourceLink)), nil, nil
 				}
-
-				// For files < 1MB, get content directly from Contents API
-				content, err := fileContent.GetContent()
-				if err != nil {
-					return utils.NewToolResultError(fmt.Sprintf("failed to decode file content: %s", err)), nil, nil
+				if !inspection.ContentAvailable {
+					return utils.NewToolResultError(fmt.Sprintf("failed to inspect repository file: Contents API did not provide content for path %q", path)), nil, nil
 				}
 
 				// Detect content type from the actual content bytes,
 				// mirroring the original approach of using the Content-Type header
 				// from the raw API response.
-				contentBytes := []byte(content)
+				contentBytes := inspection.Content
 				contentType := http.DetectContentType(contentBytes)
 
 				// Determine if content is text or binary based on detected content type
@@ -1124,18 +1155,26 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool
 				if isTextContent {
 					result := &mcp.ResourceContents{
 						URI:      resourceURI,
-						Text:     content,
+						Text:     string(contentBytes),
 						MIMEType: contentType,
 					}
-					return attachIFC(utils.NewToolResultResource(fmt.Sprintf("successfully downloaded text file (SHA: %s)%s", fileSHA, successNote), result)), nil, nil
+					message := fmt.Sprintf("successfully downloaded text file (SHA: %s)%s", fileSHA, successNote)
+					if inspection.Symlink != nil {
+						message = marshalRepositorySymlinkMetadata(inspection.Symlink, dereferencedContentLabel, successNote)
+					}
+					return attachIFC(utils.NewToolResultResource(message, result)), nil, nil
 				}
 
 				result := &mcp.ResourceContents{
 					URI:      resourceURI,
 					Blob:     contentBytes,
 					MIMEType: contentType,
 				}
-				return attachIFC(utils.NewToolResultResource(fmt.Sprintf("successfully downloaded binary file (SHA: %s)%s", fileSHA, successNote), result)), nil, nil
+				message := fmt.Sprintf("successfully downloaded binary file (SHA: %s)%s", fileSHA, successNote)
+				if inspection.Symlink != nil {
+					message = marshalRepositorySymlinkMetadata(inspection.Symlink, dereferencedContentLabel, successNote)
+				}
+				return attachIFC(utils.NewToolResultResource(message, result)), nil, nil
 			} else if dirContent != nil {
 				// file content or file SHA is nil which means it's a directory
 				filtered := false

pkg/github/repositories_helper.go

@@ -1,13 +1,17 @@
 package github
 
 import (
+	"bytes"
 	"context"
+	"crypto/sha1" //nolint:gosec // Git object IDs are defined using SHA-1.
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"net/http"
 	"net/url"
 	pathpkg "path"
 	"strings"
+	"unicode/utf8"
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/raw"
@@ -92,7 +96,45 @@ func createReferenceFromDefaultBranch(ctx context.Context, client *github.Client
 	return createdRef, nil
 }
 
-const gitSymlinkMode = "120000"
+const (
+	gitSymlinkMode             = "120000"
+	gitSubmoduleMode           = "160000"
+	maxGitTreeTraversalDepth   = 64
+	dereferencedContentLabel   = "dereferenced_target"
+	unavailableSymlinkContents = "not_returned"
+)
+
+type repositorySymlink struct {
+	Path               string
+	SHA                string
+	Target             string
+	ResolvedTargetPath string
+	Explicit           bool
+}
+
+type repositoryFileInspection struct {
+	Content          []byte
+	ContentAvailable bool
+	Symlink          *repositorySymlink
+	Submodule        *repositorySubmoduleReadMetadata
+}
+
+type repositorySymlinkReadMetadata struct {
+	Type               string `json:"type"`
+	Path               string `json:"path"`
+	SHA                string `json:"sha,omitempty"`
+	Target             string `json:"target"`
+	ResolvedTargetPath string `json:"resolved_path,omitempty"`
+	Content            string `json:"content"`
+	Note               string `json:"note,omitempty"`
+}
+
+type repositorySubmoduleReadMetadata struct {
+	Type   string `json:"type"`
+	Path   string `json:"path"`
+	SHA    string `json:"sha,omitempty"`
+	GitURL string `json:"git_url,omitempty"`
+}
 
 type symlinkWriteBlockedError struct {
 	Error              string `json:"error"`
@@ -129,6 +171,163 @@ func newSymlinkWriteBlockedResult(path, target string) *mcp.CallToolResult {
 	}
 }
 
+func inspectRepositoryFile(ctx context.Context, client *github.Client, owner, repo, treeish, path string, file *github.RepositoryContent) (*repositoryFileInspection, *github.Response, error) {
+	if file.GetType() == "symlink" {
+		content, available, err := suppliedRepositoryContent(file)
+		if err != nil {
+			return nil, nil, err
+		}
+		return &repositoryFileInspection{
+			Content:          content,
+			ContentAvailable: available,
+			Symlink:          newRepositorySymlink(path, file.GetSHA(), file.GetTarget(), true),
+		}, nil, nil
+	}
+
+	if file.GetType() == "submodule" || file.GetSubmoduleGitURL() != "" {
+		return &repositoryFileInspection{
+			Submodule: &repositorySubmoduleReadMetadata{
+				Type:   "submodule",
+				Path:   path,
+				SHA:    file.GetSHA(),
+				GitURL: file.GetSubmoduleGitURL(),
+			},
+		}, nil, nil
+	}
+
+	content, available, err := suppliedRepositoryContent(file)
+	if err != nil {
+		return nil, nil, err
+	}
+	if available {
+		if !looksLikeSHA(file.GetSHA()) {
+			return nil, nil, fmt.Errorf("contents API returned malformed Git blob SHA %q for path %q", file.GetSHA(), path)
+		}
+		if strings.EqualFold(gitBlobSHA1(content), file.GetSHA()) {
+			return &repositoryFileInspection{Content: content, ContentAvailable: true}, nil, nil
+		}
+
+		target, resp, err := symlinkTargetFromBlob(ctx, client, owner, repo, file.GetSHA())
+		if err != nil {
+			return nil, resp, fmt.Errorf("contents API bytes did not match the reported Git blob and the path blob was not a valid symbolic link target: %w", err)
+		}
+		return &repositoryFileInspection{
+			Content:          content,
+			ContentAvailable: true,
+			Symlink:          newRepositorySymlink(path, file.GetSHA(), target, false),
+		}, nil, nil
+	}
+
+	entry, resp, err := getTreeEntry(ctx, client, owner, repo, treeish, path)
+	if err != nil {
+		return nil, resp, err
+	}
+	if entry == nil {
+		return nil, nil, fmt.Errorf("path %q exists according to the Contents API but was not found in the Git tree", path)
+	}
+	if !looksLikeSHA(file.GetSHA()) || !strings.EqualFold(file.GetSHA(), entry.GetSHA()) {
+		return nil, nil, fmt.Errorf("contents API blob SHA %q does not match Git tree blob SHA %q for path %q", file.GetSHA(), entry.GetSHA(), path)
+	}
+
+	switch entry.GetMode() {
+	case gitSymlinkMode:
+		target, resp, err := symlinkTargetFromBlob(ctx, client, owner, repo, entry.GetSHA())
+		if err != nil {
+			return nil, resp, err
+		}
+		return &repositoryFileInspection{
+			Symlink: newRepositorySymlink(path, entry.GetSHA(), target, false),
+		}, nil, nil
+	case gitSubmoduleMode:
+		return &repositoryFileInspection{
+			Submodule: &repositorySubmoduleReadMetadata{
+				Type: "submodule",
+				Path: path,
+				SHA:  entry.GetSHA(),
+			},
+		}, nil, nil
+	default:
+		return &repositoryFileInspection{}, nil, nil
+	}
+}
+
+func suppliedRepositoryContent(file *github.RepositoryContent) ([]byte, bool, error) {
+	if file.Content != nil {
+		content, err := file.GetContent()
+		if err != nil {
+			return nil, false, fmt.Errorf("failed to decode file content: %w", err)
+		}
+		return []byte(content), true, nil
+	}
+	if file.GetType() != "symlink" && file.GetSize() == 0 {
+		return []byte{}, true, nil
+	}
+	return nil, false, nil
+}
+
+func gitBlobSHA1(content []byte) string {
+	hasher := sha1.New() //nolint:gosec // SHA-1 is required by the Git object ID format.
+	_, _ = fmt.Fprintf(hasher, "blob %d\x00", len(content))
+	_, _ = hasher.Write(content)
+	return hex.EncodeToString(hasher.Sum(nil))
+}
+
+func symlinkTargetFromBlob(ctx context.Context, client *github.Client, owner, repo, sha string) (string, *github.Response, error) {
+	target, resp, err := gitBlobBytes(ctx, client, owner, repo, sha)
+	if err != nil {
+		return "", resp, err
+	}
+	if len(target) == 0 || !utf8.Valid(target) || bytes.IndexByte(target, 0) >= 0 {
+		return "", nil, fmt.Errorf("git blob %q is not a valid symbolic link target", sha)
+	}
+	return string(target), nil, nil
+}
+
+func gitBlobBytes(ctx context.Context, client *github.Client, owner, repo, sha string) ([]byte, *github.Response, error) {
+	if !looksLikeSHA(sha) {
+		return nil, nil, fmt.Errorf("malformed Git blob SHA %q", sha)
+	}
+	content, resp, err := client.Git.GetBlobRaw(ctx, owner, repo, sha)
+	if err != nil {
+		return nil, resp, err
+	}
+	if resp != nil && resp.Body != nil {
+		_ = resp.Body.Close()
+	}
+	if !strings.EqualFold(gitBlobSHA1(content), sha) {
+		return nil, nil, fmt.Errorf("blob bytes returned by the Git Blobs API do not match SHA %q", sha)
+	}
+	return content, nil, nil
+}
+
+func newRepositorySymlink(path, sha, target string, explicit bool) *repositorySymlink {
+	return &repositorySymlink{
+		Path:               path,
+		SHA:                sha,
+		Target:             target,
+		ResolvedTargetPath: resolveRepositorySymlinkTarget(path, target),
+		Explicit:           explicit,
+	}
+}
+
+func marshalRepositorySymlinkMetadata(link *repositorySymlink, content, note string) string {
+	payload, _ := json.Marshal(repositorySymlinkReadMetadata{
+		Type:               "symlink",
+		Path:               link.Path,
+		SHA:                link.SHA,
+		Target:             link.Target,
+		ResolvedTargetPath: link.ResolvedTargetPath,
+		Content:            content,
+		Note:               strings.TrimSpace(note),
+	})
+	return string(payload)
+}
+
+func marshalRepositorySubmoduleMetadata(submodule *repositorySubmoduleReadMetadata) string {
+	payload, _ := json.Marshal(submodule)
+	return string(payload)
+}
+
 func symlinkTargetAtPath(ctx context.Context, client *github.Client, owner, repo, treeish, path string) (string, bool, *github.Response, error) {
 	entry, resp, err := getTreeEntry(ctx, client, owner, repo, treeish, path)
 	if err != nil {
@@ -141,18 +340,18 @@ func symlinkTargetAtPath(ctx context.Context, client *github.Client, owner, repo
 		return "", false, nil, nil
 	}
 
-	target, resp, err := client.Git.GetBlobRaw(ctx, owner, repo, entry.GetSHA())
+	target, resp, err := gitBlobBytes(ctx, client, owner, repo, entry.GetSHA())
 	if err != nil {
 		return "", false, resp, err
 	}
-	if resp != nil && resp.Body != nil {
-		_ = resp.Body.Close()
-	}
 	return string(target), true, nil, nil
 }
 
 func getTreeEntry(ctx context.Context, client *github.Client, owner, repo, treeish, path string) (*github.TreeEntry, *github.Response, error) {
 	segments := strings.Split(pathpkg.Clean(strings.TrimPrefix(path, "/")), "/")
+	if len(segments) > maxGitTreeTraversalDepth {
+		return nil, nil, fmt.Errorf("path %q exceeds the maximum Git tree traversal depth of %d", path, maxGitTreeTraversalDepth)
+	}
 	treeish = escapeGitTreeish(treeish)
 	for i, segment := range segments {
 		tree, resp, err := client.Git.GetTree(ctx, owner, repo, treeish, false)