Skip to content

feat(cli): add read-only inspection of a persisted flow state - #9482

Open
Keyi Yu (keyiyu0331) wants to merge 1 commit into
crewAIInc:mainfrom
keyiyu0331:feat/flow-state-inspect-cli
Open

Keyi Yu (keyiyu0331) wants to merge 1 commit into
crewAIInc:mainfrom
keyiyu0331:feat/flow-state-inspect-cli

Conversation

@keyiyu0331

Copy link
Copy Markdown

Related issue

Part of #8140 (AI-assisted; please apply llm-generated if I can't set the label).

Summary

Adds crewai flow state DB_PATH FLOW_UUID RECORD_ID [--json], which shows one
row of the flow_states table written by SQLiteFlowPersistence.

  • Scoped to the flow UUID: a record id that belongs to another flow is not shown.
  • Text output and --json output; both name the storage kind so it is not
    confused with full-object checkpoints.
  • Strictly read-only. The database is opened with mode=ro, a missing file is
    never created, and no -wal/-shm files are left behind. States still in a
    pending write-ahead log (a flow that is running) are still shown.
  • Reads with sqlite3 directly rather than through SQLiteFlowPersistence,
    because constructing that class creates the database and sets WAL mode, and
    crewai-cli does not depend on crewai. The query matches
    load_state_from_history (feat(flow): add exact historical state lookup by row id #8272), and a test checks both return the same state.
  • Existing checkpoint list/info/resume commands are unchanged.

This covers the exact-record inspection half of the ticket. Bounded history
listing depends on #8138 (#8253) and is left for a follow-up.

The ticket asks to confirm the command shape first. I went with flow state
under the existing flow group and am happy to rename or move it.

Verification

  • Tests added or updated for the changed behavior
  • Relevant tests and quality checks pass locally

lib/cli/tests/test_flow_state_cli.py (18 tests, CliRunner and temp files, no
API calls): JSON and text output, wrong UUID, unknown record id, empty store,
missing database, non-SQLite file, unsupported schema, non-object state,
invalid record ids, store left byte-identical, pending write-ahead log, and a
store written by the real SQLiteFlowPersistence. Also ran ruff check,
ruff format --check and mypy on the changed files.

Additional context

No docs changes yet; I can add a CLI docs entry with translations once the
command shape is confirmed.

Add `crewai flow state DB_PATH FLOW_UUID RECORD_ID [--json]`, which shows one
row of the flow_states table written by SQLiteFlowPersistence. The database is
opened read-only and is never created or modified. Listing a flow's history
depends on crewAIInc#8138 and is left for a follow-up.

Part of crewAIInc#8140

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WnKATbxGa5vTLtZffHkGAz
@strix-security

strix-security Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Strix Security Review

✅ No open security findings.

PR summary: Adds a `crewai flow state DB_PATH FLOW_UUID RECORD_ID [--json]` command that shows a single row of the `flow_states` table written by `SQLiteFlowPersistence`, opening the database with a read-only SQLite URI and never creating or modifying files.

Review summary

Reviewed the new read-only crewai flow state inspector end to end: the command wiring in lib/cli/src/crewai_cli/cli.py, the whole of lib/cli/src/crewai_cli/flow_state_cli.py, and the added tests. The database is opened strictly read-only through a mode=ro URI built from a fully percent-encoded path, so the argument cannot inject extra SQLite URI parameters; the row lookup is parameterised and scoped by an integer-bounded record id plus the flow UUID; and the state body is rendered through json.dumps, which escapes control characters. No privilege, tenant or data-access boundary is crossed — the command prints a local store the operator names on the command line, which that same user could already open directly. No security issues found.

Ruled out (4)
  • Can a crafted database path inject extra SQLite URI parameters (e.g. `mode=rwc`) and make the command write to the store?
    `Path.as_uri()` percent-encodes every query metacharacter (`?`, `&`, `#`, `=`, `%`), SQLite decodes back to the literal filename, and duplicate or conflicting `mode` values are rejected — verified against files literally named with `?mode=rwc`, and writes on the resulting handle fail read-only.
  • Can a database file crafted by a third party inject terminal escape sequences into what the command prints?
    Only the `Method:` and `Time:` lines are echoed unescaped, and reaching them requires the operator to voluntarily point the command at an untrusted `.db` they chose; the state body and `--json` output are escaped by `json.dumps`, no privileged action follows, and `crewai checkpoint info` already pr…
  • Does dumping the whole persisted state expose secrets the operator could not otherwise reach?
    The only data-access input is the operator-supplied `db_path`, gated on `Path.is_file()` and `mode=ro`, so the caller already had read access to that file; the new module has no logging, telemetry or network sink, and existing `checkpoint` commands already print comparable stored content.
  • Can a file swapped between the magic-byte check and the actual open be exploited?
    Any substituted content is only ever printed to the terminal of the operator who ran the command, must be readable by that user and contain a matching `flow_states` row, and nothing is exfiltrated to the party doing the swap — no gain over the directory write access they already needed.

Review 1 on this PR · a0c2199 · requested Nov 16 02:28 UTC when the PR was opened


Reviewed by Strix
Re-run review · Configure security review settings · Try a deeper review with @strix-security /deep

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant