You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(workflows): harden persisted workflow run artifact access against symlinks - #5480
Closes#4914. Supersedes #4930, which went stale with conflicts against main. This PR keeps all commits from #4930 and their original authors, rebased onto current main.
Persisted workflow runs now share one storage boundary in RunState. Symlinked storage ancestors (.specify, workflows, runs), per-run directories, and the known artifacts (state.json, inputs.json, workflow.yml, log.jsonl) — as well as Windows reparse points (including directory junctions) — are rejected before any read or write. RunState shares FileHelper's deny-mode entry classification (FileHelper._entry_mode), directory traversal flags (FileHelper._directory_flags), and Windows handle-backed reads (FileHelper.read_bytes) while retaining descriptor-backed directory creation, run enumeration, owner-only (0600) atomic JSON replacement, and append-only log writes where the platform supports directory descriptors. Other descriptor-free operations recheck path components with lstat() before access. Under --json, workflow status, status <run_id>, and resume write errors to stderr (or as {"error": ...} on stderr under definition --json) with exit code 1; in text mode, run and listing handlers follow the existing _error_console(False) convention on stdout while shared-ancestor preflight uses stderr, all exiting with code 1.
list_runs() skips entries whose names are not valid run IDs and handles per-run artifact OSErrors (such as unsearchable sibling run directories) inside the per-run try block while propagating symlink and reparse policy errors.
A symlink encountered by a no-follow open after the pre-checks raises the same policy error as one that existed beforehand, not a raw ELOOP or ENOTDIR.
RunState delegates entry classification to FileHelper._entry_mode() (SymlinkDeniedError / UnsupportedPathError), reuses FileHelper._directory_flags() (O_PATH / O_SEARCH) for directory traversal (requesting O_RDONLY on runs only when list_runs() enumerates entries), routes Windows descriptor-free reads through a deny-mode FileHelper(project_root) for handle-backed read-race protection, closes descriptors if os.fdopen() fails, catches FileExistsError on dangling run symlinks in portable mode, wraps storage policy failures in CheckpointError during RunState.save(), and rejects legacy inputs.json containing JSON null.
Atomic JSON writes set O_BINARY again, as tempfile.mkstemp did. Without it, Windows would write \r\r\n line endings.
Policy (as documented): the paths above are rejected when accessed. Unknown entries and unused artifacts are not scanned. A symlinked or junctioned entry whose name is a valid run ID fails the run listing.
Testing
Tested locally with .venv/bin/specify --help
Ran relevant existing and new workflow/storage and FileHelper tests with .venv/bin/python -m pytest -n auto tests/specify_cli/workflows/test_run_state_storage.py tests/specify_cli/workflows/test_command_status.py tests/specify_cli/workflows/test_command_definition.py tests/specify_cli/workflows/test_operation_list.py tests/test_workflows.py tests/workflows/test_composition_execution.py tests/test_file_helper.py -q: 1744 passed, 108 skipped (Linux, Python 3.14)
Tested with a sample project: CLI checks of status, status <id> (text and --json), resume, and definition --json against a symlinked run directory, a symlinked state.json, and a file in place of a run directory all exit with code 1 and the policy message.
Regression evidence: running the new tests from this branch against origin/main sources, 28 of 30 initial storage, status, and definition symlink tests fail, and all pass on this branch; the portable dangling-run test failed before a2d210fc with FileExistsError and passes after; the search-only traversal and unsearchable sibling-run listing tests failed before 97fee91e with PermissionError and pass after. Portable reparse-point checks are exercised on Linux via lstat() simulation alongside native Windows mklink /J coverage (skipped on non-Windows). The descriptor-free fallback is exercised on Linux by forcing _supports_descriptor_access() to False.
AI Disclosure
I did not use AI assistance for this contribution
I did use AI assistance (fill in the disclosure below)
AI disclosure: Opened by GitHub Copilot CLI on behalf of @markuswondrak, running autonomously. The original commits come from the repository's bug-fix workflow, copilot-swe-agent, and @mnriem (GPT-6.1 Sol via GitHub Copilot), as their trailers show. GitHub Copilot CLI (Gemini 4 Argon, autonomous) rebased them onto main and adapted them to #4912 and #5225. GitHub Copilot CLI (Claude Opus 5.5, autonomous) reviewed the result against #4914 and implemented follow-up fixes. GitHub Copilot CLI (Gemini 4 Carbon, interactive walkthrough with @markuswondrak) addressed the first round of PR review findings in 9d9f1e5. Antigravity (Gemini 4 Argon (High), interactive review-findings walkthrough with @markuswondrak, autonomous code generation) addressed the second and third rounds of review findings in a2d210f and 97fee91. Code, tests, docs, and this description are AI-generated. No claim of human line-by-line code review is made.
Close artifact handles in the symlink regression and explain cleanup failure handling. Forward directory descriptors through checkpoint test mocks to preserve failure and interrupt coverage.
Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 67a8a13d-1542-470f-87b8-5a3a1dc122f5
Walk storage ancestors using descriptor-relative no-follow opens and use directory descriptors for creation and listing. Reject dangling run-root symlinks and add ancestor replacement regressions while preserving the portable fallback.
Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 67a8a13d-1542-470f-87b8-5a3a1dc122f5
Create portable atomic-write temporary files with explicit 0600 permissions. Cover temporary and final state/input modes under a permissive POSIX umask, including replacement of existing files. Clarify that symlink rejection is enforced on accessed storage paths, not a proactive tree scan.
Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 67a8a13d-1542-470f-87b8-5a3a1dc122f5
…ently
- list_runs() ignores entries whose names are not valid run IDs instead of
failing the whole listing; such entries can never be run directories.
- Descriptor-relative no-follow opens confirm a symlink with lstat and raise
the same policy ValueError as the pre-access checks, instead of a raw
ELOOP/ENOTDIR OSError.
- Atomic JSON writes request O_BINARY so Windows does not double the CR of
CRLF newlines (tempfile.mkstemp set this flag before).
- Clarify the listing policy in docs and refresh the RunState.load docstring.
Assisted-by: GitHub Copilot CLI (model: Claude Opus 5.5, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This PR centralizes persisted workflow-run storage checks in RunState to address #4914, including the snapshot reads shared by resume and workflow definition.
Handles run-listing storage errors and skips entries with invalid run-ID names.
Adds storage regression coverage and documents the symlink policy and platform limits.
AI-generated review for the requester (identity unavailable): GitHub Copilot, model unknown, autonomous mode; source analysis and isolated standard-library checks. Project tests were not run.
File
Description
tests/workflows/test_composition_execution.py
Updates checkpoint mocks to forward directory descriptors.
tests/test_workflows.py
Routes listing-error mocks through the shared artifact opener.
- Reject Windows reparse points (including directory junctions) via lstat() in
RunState._reject_symlink() and _open_no_follow(), and route _run_directory()
and list_runs() through _reject_symlink().
- Close opened file descriptors in _open_artifact() and _atomic_write_json()
if os.fdopen() fails (such as IsADirectoryError on a directory artifact).
- Remove the redundant pre-lock _run_directory() call in RunState.save() so
symlink or reparse-point failures consistently set _checkpoint_failed and
raise CheckpointError.
- Use try/except FileNotFoundError/else when reading legacy inputs.json in
RunState.load() so a JSON null sidecar raises ValueError instead of being
treated as missing.
- Pin _supports_descriptor_access() before patching os.open in the O_BINARY
temporary-file test, and cover both text and --json modes for status list
storage errors.
Assisted-by: GitHub Copilot CLI (model: Gemini 4 Carbon, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
RunState._reject_symlink() and _open_no_follow() now inspect lstat() for both S_ISLNK and FILE_ATTRIBUTE_REPARSE_POINT, _run_directory() and list_runs() delegate to _reject_symlink(), and portable plus native Windows junction tests and docs were added.
RunState._open_artifact() and _atomic_write_json() close the opened file descriptor if os.fdopen() raises, with descriptor-leak regression coverage for directory artifacts.
Removed the redundant pre-lock _run_directory() call in RunState.save() so symlink and reparse-point failures consistently set _checkpoint_failed and raise CheckpointError.
RunState.load() uses try / except FileNotFoundError / else for legacy inputs.json reads so JSON null raises ValueError instead of being treated as missing.
Pinned _supports_descriptor_access() before patching os.open in test_atomic_json_writes_request_binary_descriptors and verified dir_fd usage in both modes.
Kept _error_console(json_output) in command_status.py for consistency with status <run_id>, resume, and run, added text-mode coverage in test_command_status.py, and updated the PR description accordingly (replied inline on that thread).
Validation: .venv/bin/python -m pytest -n auto tests/specify_cli/workflows/test_run_state_storage.py tests/specify_cli/workflows/test_command_status.py tests/specify_cli/workflows/test_command_definition.py tests/specify_cli/workflows/test_operation_list.py tests/test_workflows.py tests/workflows/test_composition_execution.py -q (1268 passed, 4 skipped on Linux, Python 3.11; native Windows junction test requires Windows and was skipped locally).
Posted by GitHub Copilot CLI (model: Gemini 4 Carbon, interactive session, no human line-by-line code review claimed) on behalf of @markuswondrak. Code, tests, docs, and this summary are AI-generated.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Portable-mode writes report misleading errors for dangling run-directory symlinks, and the API documentation incorrectly promises rejection for operations that can safely complete.
No open issues 🎉
3 previously missed issues
In code that hasn't changed since last review
Narrow symlink error guarantees to no-follow opens
docs/workflows/api.md:290
Descriptor-backed operations can safely finish against an already-open directory, and atomic JSON writes can replace a late artifact symlink without following it. This sentence incorrectly promises an error for those cases; limit the guarantee to symlinks encountered by no-follow opens and document the safe completion cases.
Handle dangling run symlinks in descriptor-free mode
src/specify_cli/workflows/engine.py:691
In the descriptor-free fallback, a dangling symlink at runs/<run_id> makes mkdir(exist_ok=True) raise FileExistsError before _reject_symlink() runs. Consequently, save() wraps a misleading “File exists” error, while snapshot and log writes also miss the policy error reported by reads and descriptor-backed writes. Catch FileExistsError as the descriptor branch does, let the common validation inspect the entry, and add a portable-mode dangling-run test.
Clarify why workflow runs bypass FileHelper
src/specify_cli/workflows/engine.py:738
Please clarify why workflow runs add a separate no-follow filesystem layer instead of following the ownership and migration guidance in design/file-helper.md (introduction; “Safety limits and migration,” lines 431–434). The implementations already differ in Windows read-race protection, so future hardening must be maintained twice. Either reuse a deny-mode FileHelper, extending missing operations, or document the rationale for a separate boundary.
…gling runs
- Delegate RunState._reject_symlink() and _open_no_follow() entry classification
to FileHelper._entry_mode(), raising SymlinkDeniedError and
UnsupportedPathError instead of maintaining duplicate lstat/reparse logic.
- Route Windows descriptor-free artifact reads in RunState._open_artifact()
through a deny-mode FileHelper(project_root) for handle-backed read-race
protection while preserving IsADirectoryError and policy errors.
- Validate run_dir before creation and catch FileExistsError across both
branches of RunState._run_directory(..., create=True) so dangling run
symlinks raise the symlink policy error in portable mode.
- Narrow the late-symlink guarantee in docs/workflows/api.md to no-follow opens
and document the FileHelper boundary in docs/workflows/api.md and
design/file-helper.md.
Assisted-by: Antigravity (model: Gemini 4 Argon (High), autonomous)
Addressed the review feedback from pullrequestreview-5957407533 in a2d210f:
Narrow symlink error guarantees in docs/workflows/api.md: Scoped the late-symlink policy-error guarantee to symlinks encountered by no-follow opens, and documented that already-open directory descriptors continue against that directory if its path is replaced and atomic JSON writes replace a late artifact symlink in that directory without following it.
Handle dangling run symlinks in descriptor-free mode (src/specify_cli/workflows/engine.py): Validated run_dir before creation and caught FileExistsError across both branches of RunState._run_directory(..., create=True) so dangling run-directory symlinks in portable mode report the symlink policy error instead of FileExistsError. Added test_dangling_run_directory_symlink_reports_policy_error ([False, True]).
Share FileHelper primitives and document the persisted-run boundary (src/specify_cli/workflows/engine.py, design/file-helper.md, docs/workflows/api.md): Delegated RunState._reject_symlink() and _open_no_follow() entry classification to FileHelper._entry_mode() (raising SymlinkDeniedError and UnsupportedPathError), routed Windows descriptor-free artifact reads in RunState._open_artifact() through a deny-mode FileHelper(project_root) (_read_with_file_helper()) for parent-relative handle-backed read-race protection while preserving IsADirectoryError and policy errors, and documented in design/file-helper.md and docs/workflows/api.md why RunState retains its dir_fd-anchored mkdir, listdir, 0600 atomic JSON rename, and append-only log.jsonl writes.
Earlier dismissed finding (resolved in this review):command_status.py retains cli._error_console(json_output) so workflow status matches the existing error-stream convention used by workflow status <run_id>, workflow resume, and workflow run (stdout in text mode, stderr under --json).
Posted by Antigravity (model: Gemini 4 Argon (High), interactive review-findings session, autonomous code generation, no human line-by-line code review claimed) on behalf of @markuswondrak. Analysis, code, tests, docs, and this summary are AI-generated.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
New workflow logs can expose input values from validation errors to other local users because they are created without owner-only permissions.
No open issues 🎉
3 previously missed issues
In code that hasn't changed since last review
Create workflow logs with owner-only permissions
src/specify_cli/workflows/engine.py:938
log.jsonl is created as 0644 under the common 022 umask, so other local users can read it when the project directories are traversable. Workflow-call input validation includes supplied values in errors, and those errors are written verbatim to this log, bypassing the 0600 protection on state and inputs. Create new logs with owner-only permissions in both the descriptor-backed and portable open paths.
AI-generated review for the requester (identity unavailable): GitHub Copilot, model unknown, autonomous mode; analysis, verification, and wording.
Use search-only flags when traversing run directories
src/specify_cli/workflows/engine.py:811
Known-artifact access now requires directory-read permission on POSIX because traversal uses O_RDONLY. A search-only directory (for example, mode 0111) blocks otherwise readable run state; the per-run open at line 865 has the same issue. Use FileHelper._directory_flags() for traversal while preserving project-root aliases, and request a readable runs descriptor only when listing.
AI-generated review for the requester (identity unavailable): GitHub Copilot, model unknown, autonomous mode; analysis, verification, and wording.
Handle run artifact permission errors inside the per-run try
src/specify_cli/workflows/engine.py:1945
When a run directory cannot be searched, _run_artifact() raises PermissionError before the per-run handler, aborting workflow status instead of returning readable runs. Move this call inside the existing try so ordinary I/O failures are skipped. Symlink and reparse-point refusals still propagate because they are ValueErrors.
AI-generated review for the requester (identity unavailable): GitHub Copilot, model unknown, autonomous mode; analysis, verification, and wording.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Permission-handling regressions can abort run listings on unreadable directories and block status, definition, and resume for otherwise readable artifacts in search-only directories.
… runs
- Reuse FileHelper._directory_flags() (O_PATH/O_SEARCH) when traversing storage
ancestors and per-run directories in _open_runs_directory() and
_open_run_directory(), requesting O_RDONLY on the runs directory only when
list_runs() enumerates entries.
- Move RunState._run_artifact(..., "state.json") inside the per-run try block
in WorkflowEngine.list_runs() so an unsearchable sibling run directory
(PermissionError) is skipped rather than aborting listing, while symlink and
reparse-point policy errors (ValueError subclasses) still propagate.
- Add regression tests for search-only storage directories and unsearchable
sibling run directories in list_runs().
Assisted-by: Antigravity (model: Gemini 4 Argon (High), autonomous)
Addressed the review feedback from pullrequestreview-5963339905 in 97fee91:
Use search-only flags when traversing run directories (src/specify_cli/workflows/engine.py): Reused FileHelper._directory_flags() (O_PATH / O_SEARCH) in RunState._open_runs_directory() and _open_run_directory() (clearing O_NOFOLLOW only on the trusted project_root open), requesting O_RDONLY on the runs directory only when WorkflowEngine.list_runs() enumerates entries (readable=True). Added test_search_only_storage_directories_allow_run_access_and_listing.
Handle run artifact permission errors inside the per-run try (src/specify_cli/workflows/engine.py): Moved RunState._run_artifact(self.project_root, run_dir.name, "state.json") inside the per-run try ... except (json.JSONDecodeError, OSError, UnicodeDecodeError): block in WorkflowEngine.list_runs() so an unsearchable sibling run directory (PermissionError) is skipped while symlink and reparse-point policy refusals (ValueError subclasses) still propagate. Added test_list_runs_skips_unsearchable_run_directory ([False, True]).
Deferred — Create workflow logs with owner-only permissions (src/specify_cli/workflows/engine.py): Deferred to keep main's existing creation semantics for log.jsonl (0666 filtered by umask, matching main's open(runs_dir / "log.jsonl", "a")). state.json and inputs.json use 0600 only to preserve tempfile.mkstemp() parity from main, and changing log.jsonl's permission policy is outside #4914's symlink-hardening scope.
Earlier dismissed finding (resolved):command_status.py retains cli._error_console(json_output) so workflow status matches the existing error-stream convention used by workflow status <run_id>, workflow resume, and workflow run (stdout in text mode, stderr under --json).
Posted by Antigravity (model: Gemini 4 Argon (High), interactive review-findings session, autonomous code generation, no human line-by-line code review claimed) on behalf of @markuswondrak. Analysis, code, tests, docs, and this summary are AI-generated.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
When state.json or workflow.yml is a directory, the surfaced error shows a numeric file descriptor instead of the artifact path, obscuring what users need to repair.
Please address Copilot feedback. If not applicable, please explain why. And also fix test & lint errors
This branch has not been deployed
No deployments
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
triage-must-haveVerdict: high-value, important work for Spec Kit — do first
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Closes #4914. Supersedes #4930, which went stale with conflicts against
main. This PR keeps all commits from #4930 and their original authors, rebased onto currentmain.Persisted workflow runs now share one storage boundary in
RunState. Symlinked storage ancestors (.specify,workflows,runs), per-run directories, and the known artifacts (state.json,inputs.json,workflow.yml,log.jsonl) — as well as Windows reparse points (including directory junctions) — are rejected before any read or write.RunStatesharesFileHelper's deny-mode entry classification (FileHelper._entry_mode), directory traversal flags (FileHelper._directory_flags), and Windows handle-backed reads (FileHelper.read_bytes) while retaining descriptor-backed directory creation, run enumeration, owner-only (0600) atomic JSON replacement, and append-only log writes where the platform supports directory descriptors. Other descriptor-free operations recheck path components withlstat()before access. Under--json,workflow status,status <run_id>, andresumewrite errors to stderr (or as{"error": ...}on stderr underdefinition --json) with exit code 1; in text mode, run and listing handlers follow the existing_error_console(False)convention on stdout while shared-ancestor preflight uses stderr, all exiting with code 1.Changes on top of #4930:
specify workflow definitionfor run-scoped definitions #4912.RunState.definition_pathandload_definition()go through the safe opener, soresumeandworkflow definitionshare the boundary._safe_json_loadand_safe_yaml_loadare kept.docs/workflows/api.md,docs/workflows/cli.md, anddesign/file-helper.md, following docs: consolidate and correct workflow documentation #5225.list_runs()skips entries whose names are not valid run IDs and handles per-run artifactOSErrors (such as unsearchable sibling run directories) inside the per-runtryblock while propagating symlink and reparse policy errors.ELOOPorENOTDIR.RunStatedelegates entry classification toFileHelper._entry_mode()(SymlinkDeniedError/UnsupportedPathError), reusesFileHelper._directory_flags()(O_PATH/O_SEARCH) for directory traversal (requestingO_RDONLYonrunsonly whenlist_runs()enumerates entries), routes Windows descriptor-free reads through a deny-modeFileHelper(project_root)for handle-backed read-race protection, closes descriptors ifos.fdopen()fails, catchesFileExistsErroron dangling run symlinks in portable mode, wraps storage policy failures inCheckpointErrorduringRunState.save(), and rejects legacyinputs.jsoncontaining JSONnull.O_BINARYagain, astempfile.mkstempdid. Without it, Windows would write\r\r\nline endings.Policy (as documented): the paths above are rejected when accessed. Unknown entries and unused artifacts are not scanned. A symlinked or junctioned entry whose name is a valid run ID fails the run listing.
Testing
.venv/bin/specify --helpFileHelpertests with.venv/bin/python -m pytest -n auto tests/specify_cli/workflows/test_run_state_storage.py tests/specify_cli/workflows/test_command_status.py tests/specify_cli/workflows/test_command_definition.py tests/specify_cli/workflows/test_operation_list.py tests/test_workflows.py tests/workflows/test_composition_execution.py tests/test_file_helper.py -q: 1744 passed, 108 skipped (Linux, Python 3.14)status,status <id>(text and--json),resume, anddefinition --jsonagainst a symlinked run directory, a symlinkedstate.json, and a file in place of a run directory all exit with code 1 and the policy message.Regression evidence: running the new tests from this branch against
origin/mainsources, 28 of 30 initial storage, status, and definition symlink tests fail, and all pass on this branch; the portable dangling-run test failed beforea2d210fcwithFileExistsErrorand passes after; the search-only traversal and unsearchable sibling-run listing tests failed before97fee91ewithPermissionErrorand pass after. Portable reparse-point checks are exercised on Linux vialstat()simulation alongside native Windowsmklink /Jcoverage (skipped on non-Windows). The descriptor-free fallback is exercised on Linux by forcing_supports_descriptor_access()toFalse.AI Disclosure
AI disclosure: Opened by GitHub Copilot CLI on behalf of @markuswondrak, running autonomously. The original commits come from the repository's bug-fix workflow, copilot-swe-agent, and @mnriem (GPT-6.1 Sol via GitHub Copilot), as their trailers show. GitHub Copilot CLI (Gemini 4 Argon, autonomous) rebased them onto
mainand adapted them to #4912 and #5225. GitHub Copilot CLI (Claude Opus 5.5, autonomous) reviewed the result against #4914 and implemented follow-up fixes. GitHub Copilot CLI (Gemini 4 Carbon, interactive walkthrough with @markuswondrak) addressed the first round of PR review findings in 9d9f1e5. Antigravity (Gemini 4 Argon (High), interactive review-findings walkthrough with @markuswondrak, autonomous code generation) addressed the second and third rounds of review findings in a2d210f and 97fee91. Code, tests, docs, and this description are AI-generated. No claim of human line-by-line code review is made.