Skip to content

Commit e3f9c76

Browse files
committed
fix: close symlink-listing, TOCTOU, and skip-count gaps in grep_file/list_files
Addresses 4 issues mesutoezdil found in review on PR #2267: - ListDirContent listed a directory symlink (e.g. every session's "skills" entry) as a file instead of a directory, since entry.IsDir() doesn't follow symlinks. Now stats symlink entries to classify them correctly, matching Python's existing symlink-following behavior. - classifyWalkEntry verified a walked entry's resolved, in-bounds target, but grepFile then reopened the original unresolved path -- a verify-then-use gap where the symlink's target could differ between the check and the read. grepFile now reads the resolved path that was actually verified. This narrows the race but doesn't fully eliminate it (documented in a comment on classifyWalkEntry); closing it completely would need platform-specific work disproportionate to this file's existing security bar. - Go and Python both silently dropped the "N entries could not be read" note whenever there were also real matches, only surfacing it when the result was otherwise empty -- masking partial failures. Both now append it alongside real matches too. Verified end-to-end on a live kind cluster via A2A against redeployed Go- and Python-runtime test agents, extracting raw tool function_response payloads (not model-summarized text) to confirm each fix's actual behavior, plus a targeted regression check confirming symlink-escape protection still holds after the refactor. Signed-off-by: brandonkeung <[email protected]>
1 parent a56d813 commit e3f9c76

4 files changed

Lines changed: 161 additions & 17 deletions

File tree

‎go/adk/pkg/skills/shell.go‎

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,18 @@ func ListDirContent(path string) (string, error) {
129129
continue
130130
}
131131

132+
// entry.IsDir() reflects the entry's own type (Lstat-like) and is
133+
// false for a symlink even when its target is a directory -- e.g.
134+
// the "skills" symlink present in every session dir. Stat (which
135+
// follows symlinks) to classify those correctly, matching Python's
136+
// pathlib Path.is_dir(), which follows symlinks by default.
137+
if entry.Type()&fs.ModeSymlink != 0 {
138+
if target, statErr := os.Stat(filepath.Join(path, entry.Name())); statErr == nil && target.IsDir() {
139+
fmt.Fprintf(&result, "%s/\n", entry.Name())
140+
continue
141+
}
142+
}
143+
132144
info, err := entry.Info()
133145
if err != nil {
134146
fmt.Fprintf(&result, "%s\n", entry.Name())
@@ -164,38 +176,51 @@ const (
164176

165177
// classifyWalkEntry decides how GrepContent's WalkDir callback should treat
166178
// p, given the resolved search root. It never opens p for reading -- the
167-
// caller is responsible for that once this returns walkEntryGrep.
168-
func classifyWalkEntry(root, p string, d fs.DirEntry) walkEntryAction {
179+
// caller is responsible for that once this returns walkEntryGrep, and must
180+
// read the returned resolved path rather than p itself: p is the symlink
181+
// as walked, and re-resolving or reopening it separately from this check
182+
// would reintroduce a TOCTOU window where the symlink's target could change
183+
// between the check and the read.
184+
//
185+
// This narrows that window but doesn't eliminate it: resolved is still a
186+
// path string, so the later os.Open on it is a fresh lookup, not an
187+
// operation on a captured file handle. A path component of resolved could
188+
// still be swapped out between this check and that open. Closing that
189+
// residual race fully would need platform-specific work (e.g. Linux's
190+
// openat2 with RESOLVE_NO_SYMLINKS), which isn't done anywhere else in this
191+
// file either -- this function only guarantees "reads what was just
192+
// verified", not "reads atomically with no concurrent tampering".
193+
func classifyWalkEntry(root, p string, d fs.DirEntry) (walkEntryAction, string) {
169194
if d.IsDir() {
170-
return walkEntrySkip
195+
return walkEntrySkip, ""
171196
}
172197
resolved, err := filepath.EvalSymlinks(p)
173198
if err != nil {
174-
return walkEntryUnreadable
199+
return walkEntryUnreadable, ""
175200
}
176201
fi, statErr := os.Stat(resolved)
177202
if statErr != nil {
178-
return walkEntryUnreadable
203+
return walkEntryUnreadable, ""
179204
}
180205
if fi.IsDir() {
181206
// p is a symlink to a directory: WalkDir doesn't recurse into
182207
// symlinked directories, and grepFile would fail trying to read
183208
// one as a file, so skip it rather than treating it as an error.
184-
return walkEntrySkip
209+
return walkEntrySkip, ""
185210
}
186211
if !fi.Mode().IsRegular() {
187212
// Skip non-regular files (FIFOs, sockets, devices): opening one
188213
// for reading can block indefinitely (e.g. a FIFO with no writer
189214
// connected), and grep has no business reading them.
190-
return walkEntrySkip
215+
return walkEntrySkip, ""
191216
}
192217
if !WithinRoot(resolved, root) {
193218
// The symlink-resolved target escapes the root being searched, so
194219
// a symlink can't be used to read files outside the requested
195220
// directory.
196-
return walkEntrySkip
221+
return walkEntrySkip, ""
197222
}
198-
return walkEntryGrep
223+
return walkEntryGrep, resolved
199224
}
200225

201226
// GrepContent searches path for lines matching a regular expression pattern.
@@ -216,6 +241,7 @@ func GrepContent(path, pattern string, recursive, ignoreCase bool) (string, erro
216241
}
217242

218243
var result strings.Builder
244+
var skipped int
219245
grepFile := func(filePath string) error {
220246
file, err := os.Open(filePath)
221247
if err != nil {
@@ -254,7 +280,6 @@ func GrepContent(path, pattern string, recursive, ignoreCase bool) (string, erro
254280
// its root argument, so if path itself were an unresolved directory
255281
// symlink, WalkDir would see a non-directory at the root and never
256282
// descend into it at all.
257-
var skipped int
258283
err = filepath.WalkDir(root, func(p string, d fs.DirEntry, walkErr error) error {
259284
if walkErr != nil {
260285
if p == root {
@@ -272,22 +297,19 @@ func GrepContent(path, pattern string, recursive, ignoreCase bool) (string, erro
272297
skipped++
273298
return nil
274299
}
275-
switch classifyWalkEntry(root, p, d) {
300+
switch action, resolved := classifyWalkEntry(root, p, d); action {
276301
case walkEntryUnreadable:
277302
skipped++
278303
case walkEntryGrep:
279304
// A read error on one file (permission denied, a line
280305
// exceeding the scan buffer, etc.) shouldn't abort matches
281306
// already found elsewhere in the tree.
282-
if grepErr := grepFile(p); grepErr != nil {
307+
if grepErr := grepFile(resolved); grepErr != nil {
283308
skipped++
284309
}
285310
}
286311
return nil
287312
})
288-
if err == nil && skipped > 0 && result.Len() == 0 {
289-
return fmt.Sprintf("no matches found (%d entries could not be read)", skipped), nil
290-
}
291313
} else {
292314
if !info.Mode().IsRegular() {
293315
return "", fmt.Errorf("%q is not a regular file", path)
@@ -299,10 +321,17 @@ func GrepContent(path, pattern string, recursive, ignoreCase bool) (string, erro
299321
}
300322

301323
if result.Len() == 0 {
324+
if skipped > 0 {
325+
return fmt.Sprintf("no matches found (%d entries could not be read)", skipped), nil
326+
}
302327
return "no matches found", nil
303328
}
304329

305-
return strings.TrimSuffix(result.String(), "\n"), nil
330+
matches := strings.TrimSuffix(result.String(), "\n")
331+
if skipped > 0 {
332+
matches += fmt.Sprintf("\n\n(%d entries could not be read)", skipped)
333+
}
334+
return matches, nil
306335
}
307336

308337
func resolveSRTSettingsArgs() ([]string, error) {

‎go/adk/pkg/skills/shell_test.go‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -345,6 +345,26 @@ func TestListDirContent(t *testing.T) {
345345
t.Fatal("expected error for nonexistent path")
346346
}
347347
})
348+
349+
t.Run("symlink to a directory is listed as a directory", func(t *testing.T) {
350+
realDir := filepath.Join(tmpDir, "a-subdir")
351+
linkPath := filepath.Join(tmpDir, "dir-link")
352+
if err := os.Symlink(realDir, linkPath); err != nil {
353+
t.Skipf("symlinks not supported: %v", err)
354+
}
355+
defer os.Remove(linkPath)
356+
357+
result, err := ListDirContent(tmpDir)
358+
if err != nil {
359+
t.Fatalf("ListDirContent() error = %v", err)
360+
}
361+
if !strings.Contains(result, "dir-link/") {
362+
t.Errorf("expected symlinked directory to be listed with a trailing slash, got %q", result)
363+
}
364+
if strings.Contains(result, "dir-link\t") {
365+
t.Errorf("expected symlinked directory not to be listed as a file, got %q", result)
366+
}
367+
})
348368
}
349369

350370
func TestGrepContent(t *testing.T) {
@@ -437,6 +457,35 @@ func TestGrepContent(t *testing.T) {
437457
}
438458
})
439459

460+
t.Run("recursive search greps the resolved target of an in-bounds file symlink", func(t *testing.T) {
461+
realFile := filepath.Join(subDir, "real_target.txt")
462+
if err := os.WriteFile(realFile, []byte("foo via symlink\n"), 0644); err != nil {
463+
t.Fatalf("Failed to write test file: %v", err)
464+
}
465+
linkPath := filepath.Join(subDir, "file_link.txt")
466+
if err := os.Symlink(realFile, linkPath); err != nil {
467+
t.Skipf("symlinks not supported: %v", err)
468+
}
469+
defer os.Remove(linkPath)
470+
471+
result, err := GrepContent(subDir, "foo via symlink", true, false)
472+
if err != nil {
473+
t.Fatalf("GrepContent() error = %v", err)
474+
}
475+
// The match must be reported against the resolved target path
476+
// (real_target.txt), not the walked symlink path (file_link.txt):
477+
// classifyWalkEntry verifies the resolved target is in-bounds, and
478+
// the actual read must use that same resolved value rather than
479+
// re-deriving/reopening the raw symlink path, or the verified-safe
480+
// check and the actual read could diverge (TOCTOU).
481+
if !strings.Contains(result, "real_target.txt:1:foo via symlink") {
482+
t.Errorf("expected match to be reported against the resolved target path, got %q", result)
483+
}
484+
if strings.Contains(result, "file_link.txt:") {
485+
t.Errorf("expected match not to be reported against the unresolved symlink path, got %q", result)
486+
}
487+
})
488+
440489
t.Run("recursive search does not abort on an in-bounds directory symlink", func(t *testing.T) {
441490
walkDir := createTempDir(t)
442491
defer os.RemoveAll(walkDir)
@@ -635,6 +684,46 @@ func TestGrepContent(t *testing.T) {
635684
}
636685
})
637686

687+
t.Run("matches are annotated with the skip count when some entries could not be read", func(t *testing.T) {
688+
if os.Geteuid() == 0 {
689+
t.Skip("root bypasses directory permissions; cannot exercise this case")
690+
}
691+
692+
walkDir := createTempDir(t)
693+
defer os.RemoveAll(walkDir)
694+
695+
okSub := filepath.Join(walkDir, "aaa_ok")
696+
if err := os.Mkdir(okSub, 0755); err != nil {
697+
t.Fatalf("Failed to create subdir: %v", err)
698+
}
699+
if err := os.WriteFile(filepath.Join(okSub, "match.txt"), []byte("foo readable\n"), 0644); err != nil {
700+
t.Fatalf("Failed to write test file: %v", err)
701+
}
702+
703+
noPermSub := filepath.Join(walkDir, "mmm_noperm")
704+
if err := os.Mkdir(noPermSub, 0755); err != nil {
705+
t.Fatalf("Failed to create subdir: %v", err)
706+
}
707+
if err := os.WriteFile(filepath.Join(noPermSub, "hidden.txt"), []byte("foo hidden\n"), 0644); err != nil {
708+
t.Fatalf("Failed to write test file: %v", err)
709+
}
710+
if err := os.Chmod(noPermSub, 0000); err != nil {
711+
t.Fatalf("Failed to chmod subdir: %v", err)
712+
}
713+
defer os.Chmod(noPermSub, 0755)
714+
715+
result, err := GrepContent(walkDir, "foo", true, false)
716+
if err != nil {
717+
t.Fatalf("GrepContent() error = %v", err)
718+
}
719+
if !strings.Contains(result, "match.txt:1:foo readable") {
720+
t.Errorf("expected the real match to still be reported, got %q", result)
721+
}
722+
if !strings.Contains(result, "could not be read") {
723+
t.Errorf("expected the skip count to be reported alongside real matches, not silently dropped, got %q", result)
724+
}
725+
})
726+
638727
t.Run("recursive search on a fully unreadable root returns an error, not a confident empty result", func(t *testing.T) {
639728
if os.Geteuid() == 0 {
640729
t.Skip("root bypasses directory permissions; cannot exercise this case")

‎python/packages/kagent-skills/src/kagent/skills/shell.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,10 @@ def grep_file(file_path: Path) -> list[str]:
257257
return f"no matches found ({skipped} entries could not be read)"
258258
return "no matches found"
259259

260-
return "\n".join(results)
260+
output = "\n".join(results)
261+
if skipped:
262+
output += f"\n\n({skipped} entries could not be read)"
263+
return output
261264

262265

263266
# --- Shell Operation Tools ---

‎python/packages/kagent-skills/src/kagent/tests/unittests/test_skill_execution.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -519,6 +519,29 @@ def test_grep_content_recursive_does_not_abort_or_discard_matches_on_an_unreadab
519519
assert "match.txt:1:foo readable" in result
520520

521521

522+
def test_grep_content_annotates_skip_count_alongside_real_matches(tmp_path):
523+
"""A skip count found alongside real matches must not be silently dropped."""
524+
if os.geteuid() == 0:
525+
pytest.skip("root bypasses directory permissions; cannot exercise this case")
526+
527+
ok_sub = tmp_path / "aaa_ok"
528+
ok_sub.mkdir()
529+
(ok_sub / "match.txt").write_text("foo readable\n")
530+
531+
noperm_sub = tmp_path / "mmm_noperm"
532+
noperm_sub.mkdir()
533+
(noperm_sub / "hidden.txt").write_text("foo hidden\n")
534+
noperm_sub.chmod(0o000)
535+
536+
try:
537+
result = grep_content(tmp_path, "foo", recursive=True, allowed_root=tmp_path)
538+
finally:
539+
noperm_sub.chmod(0o755)
540+
541+
assert "match.txt:1:foo readable" in result
542+
assert "could not be read" in result
543+
544+
522545
def test_grep_content_no_matches_found_is_annotated_when_a_subdirectory_could_not_be_read(tmp_path):
523546
if os.geteuid() == 0:
524547
pytest.skip("root bypasses directory permissions; cannot exercise this case")

0 commit comments

Comments
 (0)